Skip to main content

Проверка переводов в CI: автоматизация проверок i18n в конвейере

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

1

Почему ошибки перевода проходят проверку кода

Разработчик добавляет 10 ключей в en.json и обновляет код функции. Проверяющий изучает код, подтверждает английские строки и утверждает изменения. Никто не сравнивает остальные 14 файлов локалей. В рабочую среду попадают три ошибки: в de.json отсутствуют 2 ключа — немецкие пользователи видят исходные пути; в fr.json нарушен заполнитель {count} — французские пользователи видят буквальный {count}; в ja.json неправильно сформирована форма ICU — японские пользователи сталкиваются с аварийным завершением. Всё это предотвращает 30-секундная проверка CI.

У ошибок перевода есть уникальное свойство: они невидимы разработчику и проверяющему и проявляются только для пользователей конкретной локали. Проверка CI — единственный надёжный способ обнаружить их до рабочей среды.
2

Установить i18n-validate

Добавьте i18n-validate в проект как зависимость разработки. Он сразу поддерживает форматы JSON, YAML, PO, XLIFF и ARB, а для базового использования конфигурация не нужна.

Terminal
npm install --save-dev @anthropic/i18n-validate
3

Интеграция с GitHub Actions

Добавьте i18n-validate как этап процесса запросов на слияние. При обнаружении ошибок инструмент завершается с кодом 1, поэтому проверка запроса не проходит. Используйте вывод JUnit XML с действием отчёта о тестах для встроенных аннотаций непосредственно в различиях запроса.

.github/workflows/i18n-validate.yml
# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - 'src/locales/**'
      - 'public/locales/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Validate translation files
        run: npx i18n-validate \
          --source src/locales/en.json \
          --targets 'src/locales/*.json' \
          --check-missing \
          --check-unused \
          --check-placeholders \
          --check-plurals \
          --min-coverage 95 \
          --junit-output reports/i18n.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: i18n-validation-report
          path: reports/i18n.xml
Закрепите версию i18n-validate в процессе, чтобы новые правила проверки не вызвали неожиданные сбои. Используйте @latest только во время разработки.
4

Интеграция с GitLab CI

Добавьте задание проверки переводов в конвейер .gitlab-ci.yml. GitLab изначально поддерживает артефакты JUnit XML: загрузите отчёт проверки, и ошибки появятся на вкладке Test запроса на слияние.

.gitlab-ci.yml
# .gitlab-ci.yml
i18n-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx i18n-validate \
        --source src/locales/en.json \
        --targets 'src/locales/*.json' \
        --check-missing \
        --check-unused \
        --check-placeholders \
        --min-coverage 95 \
        --junit-output reports/i18n.xml
  artifacts:
    reports:
      junit: reports/i18n.xml
  only:
    changes:
      - src/locales/**/*
5

Хук перед фиксацией

Для более быстрой обратной связи запускайте проверку как хук перед фиксацией. Ошибки выявляются ещё до CI, что экономит время конвейера и сокращает циклы обратной связи. Управляйте хуками через Husky (JS) или pre-commit (Python).

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Only validate if translation files changed
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(locales|i18n|translations)/')

if [ -n "$CHANGED_FILES" ]; then
  echo "Translation files changed, validating..."
  npx i18n-validate \
    --source src/locales/en.json \
    --targets 'src/locales/*.json' \
    --check-missing \
    --check-placeholders
fi
Хуки выполняются при каждой фиксации, поэтому должны оставаться быстрыми. Используйте флаг --locales, чтобы проверять только локали, изменённые в текущей фиксации, а не все. В большинстве проектов выполнение занимает менее 2 секунд.
6

Конфигурация и уровни серьёзности

Настройте поведение проверки через файл .i18n-validate.toml. Задайте для каждого правила серьёзность (error, warning, off), определите ожидаемые языки, исключите локали в работе и настройте формат вывода. В CI только ошибки приводят к сбою, а предупреждения появляются в отчёте, не блокируя процесс.

i18n-validate.config.json
// i18n-validate.config.json
{
  "source": "src/locales/en.json",
  "targets": "src/locales/*.json",
  "checks": {
    "missing": true,         // Keys in source missing from target
    "unused": true,          // Keys in target not in source
    "placeholders": true,    // Mismatched {variables}
    "plurals": true,         // Missing CLDR plural forms
    "icu": true,             // ICU syntax validation
    "emptyValues": true,     // Empty string values
    "duplicateValues": false // Same value as source (untranslated)
  },
  "minCoverage": 95,
  "exclude": [
    "src/locales/pseudo.json"
  ],
  "junitOutput": "reports/i18n.xml",
  "format": "json"          // json | yaml | po | xliff
}

Попробовать i18n Agent

Перетащите сюда файл перевода

JSON, YAML, PO, XML, CSV, Markdown, Properties

или нажмите, чтобы выбрать

Целевые языки

Регистрация не требуетсяМгновенный расчёт

Частые вопросы о проверке переводов в CI