Skip to main content

Перевірка перекладів у CI: автоматизація перевірок i18n у Вашому pipeline

Помилки перекладу непомітні під час перевірки коду. Відсутній ключ, пошкоджений заповнювач або неправильно сформована форма множини не відображаються в diff. Перевірка на рівні CI виявляє їх до потрапляння у виробниче середовище.

1

Чому помилки перекладу залишаються непоміченими під час перевірки коду

Розробник додає 10 нових ключів до en.json і оновлює код функції. Рецензент PR перевіряє код та англійські рядки й схвалює зміни. Ніхто не порівнює 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 як крок у workflow для pull request. Коли інструмент знаходить помилки, він завершує роботу з кодом 1, через що перевірку PR не пройдено. Використовуйте виведення JUnit XML разом з action для звітів про тести, щоб отримувати вбудовані анотації безпосередньо в diff PR.

.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 у workflow, щоб нові правила перевірки не спричинили неочікуваних збоїв. Використовуйте @latest лише під час розробки.
4

Інтеграція з GitLab CI

Додайте завдання перевірки перекладів до pipeline у .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

Хук pre-commit

Щоб швидше отримувати зворотний зв’язок, запускайте перевірку через хук pre-commit. Так проблеми буде виявлено ще до потрапляння в CI, що заощаджує час pipeline і скорочує цикл зворотного зв’язку. Для керування хуками використовуйте 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
Хуки pre-commit запускаються для кожного commit, тому мають працювати швидко. Використовуйте прапорець --locales, щоб перевіряти лише локалі, змінені в поточному commit, а не всі локалі. У більшості проєктів це дає змогу виконувати хук менш ніж за 2 секунди.
6

Конфігурація та рівні серйозності

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

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