x18n: универсальный тулкит для интернационализации и линтинга переводовЗаметка · дайджест за 9 ноября
Консольный интерфейс тулкита x18n на темном экране ноутбука с результатами линтинга локалей рядом с карточками языковых словарей en, ru и de на деревянном рабочем столе.
Заметка3 раздела≈ 4 мин

x18n: универсальный тулкит для интернационализации и линтинга переводов

Как часто перед отправкой пулреквеста ты вручную сверяешь языковые файлы проекта, чтобы на кнопке оплаты у зарубежного пользователя не вылез сырой технический ключ вместо понятной надписи? Обычно мы правим базовый словарь, проверяем страницу в браузере и сливаем ветку, надеясь на сборщик и тесты.

Вот только компилятор слеп к переводам: для него строковый идентификатор — просто текст, даже если в соседней локали такой записи нет. Как навести порядок в переводах веб-приложения и не допустить потери ключей в конвейере непрерывной интеграции (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 в твоем рабочем репозитории — сколько забытых ключей и тихих расхождений между языками всплывет в терминале?

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 5