Shipi18n

Ловите битые переводы до того, как они уйдут в релиз. QA-шлюз с открытым исходным кодом для ваших locale-файлов — и, когда нужно, движок перевода i18n, работающий на вашем собственном LLM-ключе.

Ваш es.json говорит Hola там, где английский — Hello {{name}}. Плейсхолдер пропал, сборка зелёная, и баг уходит в релиз. Shipi18n находит это — и находит более сложный случай: строку, в которой есть все плейсхолдеры, но смысл всё равно неверный.

Реальный запуск, а не макет — docs/check-demo.tape воспроизводит его.

npx @shipi18n/cli check ./locales -s en

Ни API-ключа, ни аккаунта, ни конфигурации. Отсутствующие ключи, потерянные плейсхолдеры, схлопнутые плюральные формы, пустые значения и непереведённый текст — в виде человекочитаемого вывода, JSON, SARIF (аннотации в GitHub PR) или JUnit.

Затем, когда нужно проверить смысл, приносите свой ключ. Судье нужен SDK провайдера вместе с CLI:

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n check ./locales -s en --semantic

LLM читает каждую пару и сообщает о неверных переводах, пропусках и добавлениях:

⚠ es  coverage 100.0%  0 error(s), 1 warning(s)
    warning  delete  semantic-mistranslation — Translation says 'will save' (guardará)
                     instead of 'will delete' (eliminará/borrará)

Все плейсхолдеры на месте и все ключи присутствуют, поэтому структурные проверки пропускают этот файл. Поймать баг может только чтение. По умолчанию — рекомендательный: он предупреждает, но не валит сборку.

Измерено, а не заявлено. На корпусе из 228 пар, закоммиченном до того, как судья был написан (60d699b), и с заранее зафиксированными порогами: поймано 54/54 намеренно внесённых ошибок (100%) и 12/168 ложных срабатываний на чистых парах (7.1%), при этом найдено 6/6 нарушений глоссария. Воспроизведено в двух независимых запусках (2026-08-16 и 2026-08-17) с claude-haiku-4-5, 3 проходами, ~59k токенов за 156 с. Точность меток менялась между запусками (100% → 98.1%) — это модель, так что воспринимайте эти цифры как диапазон, а не константу. Тестовый стенд — evals/semantic/. Запускайте его на своей модели.

Ничего не проходит через наши серверы, потому что их нет. Единственный сетевой вызов — с вашей машины к выбранному вами провайдеру.

Пакеты

Related MCP server: i18n Agent

Зачем

Генерация переводов — решённая задача. Полдюжины хороших инструментов заполнят ваши locale-файлы, а агент сделает это бесплатно. Но результат не проверяет никто. Ваш CI линтит ваш JavaScript, проверяет типы и запускает тесты — а затем в релиз уходит de.json, который никто не читал и который создала модель, которую никто не проверял.

Существующие проверки — структурные: они сравнивают множества ключей и на этом останавливаются. Это ловит отсутствующий ключ. Но не ловит перевод, в котором есть все ключи и все плейсхолдеры и который при этом говорит вашим немецким пользователям противоположное тому, что вы имели в виду.

Shipi18n — это тот самый недостающий шлюз, состоящий из двух уровней:

• Детерминированный, офлайн, без ключа. Отсутствующие и осиротевшие ключи, потерянные или повреждённые плейсхолдеры ({{name}}, {count}, %s, %d, %1$s, $t(...), %{name}, HTML), схлопнутые плюральные формы, пустые значения, непереведённый текст, покрытие по каждому языку.

• Семантический, с вашим собственным ключом. Проход LLM-в-роли-судьи только по изменённым ключам, с многопроходным голосованием большинством, потому что оценки судьи за один проход нестабильны. Сообщает о неверном переводе, пропуске и добавлении. По умолчанию рекомендательный: QA-инструмент, который валит сборку, удаляют.

Плюс части, которые делают его удобным в повседневной работе:

• Форматы помимо JSON. Flutter .arb и Apple .xcstrings, включая спецификаторы %@/%lld.

• Нативный для CI. Корректные коды выхода, --fail-on, --min-coverage, SARIF для аннотаций в PR, JUnit.

• Ручные правки защищены. shipi18n lock запоминает переводы, одобренные человеком, и предупреждает, если что-то перезаписывает их или если исходный текст уходит из-под них.

• Без ключа прямо из редактора. Валидаторы MCP-сервера вообще не вызывают модель.

• Он также переводит. Независимый от провайдера, сохраняющий структуру, инкрементальный — Anthropic и OpenAI из коробки, а любой объект с методом complete(prompt) является валидным адаптером.

Проверка из редактора — без API-ключа

@shipi18n/mcp приносит проверки в любой MCP-клиент. Инструменты валидации не вызывают модель, поэтому им вообще не нужен ключ:

// claude_desktop_config.json
{
  "mcpServers": {
    "shipi18n": { "command": "npx", "args": ["-y", "@shipi18n/mcp"] }
  }
}

«Проверьте ./locales на соответствие английскому и скажите, что сломано в испанском.»

review_locales идёт дальше — ему тоже не нужен ключ: он передаёт вашему агенту пары переводов и критерии ревью, а ваш агент рассуждает о смысле с помощью модели, которая у него уже есть.

Проверка в CI — ключ не нужен

Проверки работают с переводами из любого источника — TMS, другого инструмента, агента, человека. Запускайте его при каждом push:

npx @shipi18n/cli check ./locales -s en

Отсутствующие ключи, потерянные плейсхолдеры, схлопнутые плюральные формы, пустые значения и непереведённый текст — выводятся в виде человекочитаемого вывода, JSON, SARIF (аннотации в GitHub PR) или JUnit. Работает с обычными JSON-деревьями, Flutter .arb-бандлами и Apple .xcstrings-каталогами. Детерминированно и офлайн: без LLM и API-ключа.

Защита переводов, отредактированных вручную

Исправьте строку вручную, зафиксируйте её, и check предупредит, если что-то когда-либо перезапишет её — или если английский текст уйдёт из-под неё:

npx @shipi18n/cli lock ./locales --keys 'legal.*'

.shipi18n/locks.json хранит только хэши, его безопасно коммитить, и такие находки являются предупреждениями — защита ручного труда не должна блокировать пайплайн. Подробности в CLI README.

Он также переводит

Проверка работает с переводами откуда угодно, но если вы хотите, чтобы Shipi18n тоже создавал их, он это умеет — с вашим ключом, вашей моделью и без посредников.

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n translate locales/en.json -t es,fr,de

✔ es → locales/es.json (2 translated, 0 reused)

Или из Node (те же требования к SDK):

import { translateJSON } from '@shipi18n/core'

const { result, stats } = await translateJSON({
  content: { greeting: 'Hello {{name}}' },
  from: 'en',
  to: 'es',
  provider: 'anthropic',        // 'anthropic' | 'openai' | custom { complete } adapter
})
// result → { greeting: 'Hola {{name}}' }

Сохраняет структуру, безопасен для плейсхолдеров и инкрементален — модели отправляются только новые или изменённые ключи. Затем проверьте результат тем же инструментом.

Разработка

Это монорепозиторий на pnpm + turbo.

pnpm install
pnpm test          # all packages
pnpm --filter @shipi18n/core test

Версионированием управляют Changesets: pnpm changeset — чтобы добавить.

Участие в разработке

Принимаются issues и пул-реквесты — см. CONTRIBUTING.md. pnpm install && pnpm test запускает 105 тестов против mock-адаптера, так что для работы над проектом API-ключ не нужен.

Лицензия

Apache-2.0 © Shipi18n. См. NOTICE.