Как часто перед отправкой пулреквеста ты вручную сверяешь языковые файлы проекта, чтобы на кнопке оплаты у зарубежного пользователя не вылез сырой технический ключ вместо понятной надписи? Обычно мы правим базовый словарь, проверяем страницу в браузере и сливаем ветку, надеясь на сборщик и тесты.
Вот только компилятор слеп к переводам: для него строковый идентификатор — просто текст, даже если в соседней локали такой записи нет. Как навести порядок в переводах веб-приложения и не допустить потери ключей в конвейере непрерывной интеграции (CI)? Эту задачу решает открытый тулкит x18n (исходный код открыт в x18n-dev/x18n и отмечен в Best of JS) — модульный инструментарий для интернационализации (i18n, то есть адаптации программы под несколько языков).
Почему ручное управление локалями превращает словари в склад забытых ключей
Механика локализации похожа на гардероб с номерными жетонами и бумажными книгами учета. В коде не пишут фразы напрямую: программист вешает в разметку «жетон» с адресом ячейки, например t('settings.billing.card_expired'), а приложение ищет строку по номеру в английской, русской или немецкой тетради.
В веб-проекте на Vue и Nuxt с 3 локалями (en, ru, de) и 400 ключами переводов в JSON-файлах ручной учет быстро дает сбой. При рефакторинге оплаты и профиля команда переименовывает в компонентах 12 строковых констант, обновляя только locales/en.json. В итоге в ru.json и de.json теряются 12 новых ключей (клиенты видят голый путь settings.billing.card_expired), 12 старых строк лежат мертвым грузом в бандле, измененные исходные фразы и плейсхолдеры {name} устаревают в других языках, а в шаблоны попадает хардкод.
Как модульное ядро x18n, готовые пресеты и CLI-линтер ловят расхождения
Ты спросишь: «Но ведь для редакторов давно есть плагин i18n-ally — зачем понадобился новый инструмент?» Я тоже задался этим вопросом, изучая документацию. Создатель оригинального плагина Энтони Фу построил его вокруг внутреннего API VS Code, поэтому проверку нельзя было вынести в терминал на сервере CI или подключить к другим редакторам.
В x18n систему разделили на независимые слои. Ядро @x18n/core строит граф связей кода со словарями, отслеживает устаревание исходного текста (stale detection) и включает 45+ пресетов фреймворков с поддержкой JSON, YAML, PO, Fluent и INI. Папка locales/ находится автоматически без настроек, а поверх движка работают языковой сервер @x18n/lsp и браузерная панель.
Чтобы перехватить потерю 12 констант в нашем проекте на Vue и Nuxt с 3 локалями и 400 ключами, запустим консольный линтер @x18n/cli:
pnpx @x18n/cli check --strict --json
pnpx @x18n/cli usages common.buttons.submit
В нашем сценарии шаг pnpx @x18n/cli check --strict в пайплайне CI останавливает сборку с кодом 1, блокируя деплой сломанной формы оплаты. Терминал выводит 12 пропущенных ключей в ru.json и de.json и 12 старых строк под удаление, а флаг --json отдает отчет с номерами строк для скриптов и ИИ-агентов. После добавления переводов проверка возвращает код 0 (All i18n checks passed).
Ограничения автодетекта и накладные расходы при внедрении
Перед интеграцией учтем границы тулкита. Для работы CLI нужен Node.js версии 18.0.0 или выше (анализ идет локально без отправки файлов в сеть, но хранить секреты в словарях нельзя). Для редких корпоративных форматов потребуется свой плагин к @x18n/core, а для хранения типизированных словарей внутри папок компонентов вместо общих JSON-файлов подойдет компонентная интернационализация в Intlayer.
При использовании кастомных оберток вместо t() автодетект не заметит вызовы и запишет ключи в «мертвые». Чтобы задать свои функции и исключить тесты в проекте на Vue и Nuxt, добавим x18n.config.ts:
import { defineConfig } from '@x18n/core'
export default defineConfig({
sourceLocale: 'en',
resources: [{ pattern: 'locales/{locale}.json' }],
usage: {
include: ['src/**/*.vue', 'src/**/*.ts'],
exclude: ['**/*.spec.ts', '**/*.test.ts'],
calls: [{ callee: ['t', '$t', 'i18n.t'] }],
},
})
С этим конфигом и скриптом "lint:i18n": "x18n check --strict" в package.json сканер игнорирует тесты *.spec.ts, видит вызовы i18n.t и держит все 400 ключей в 3 локалях под защитой CI. А если прямо сейчас запустить pnpx @x18n/cli check в твоем рабочем репозитории — сколько забытых ключей и тихих расхождений между языками всплывет в терминале?

