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 като стъпка в работния процес за pull request. Инструментът завършва с код 1 при откриване на грешки, поради което проверката на PR е неуспешна. Използвайте изход във формат JUnit XML с действие за отчитане на тестове, за да получавате пояснения директно върху разликите в 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 в работния процес, за да избегнете неочаквани прекъсвания вследствие на нови правила за проверка. Използвайте @latest само при разработка.
4

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

Добавете задача за проверка на преводите към Вашия пайплайн в .gitlab-ci.yml. GitLab поддържа директно артефакти във формат JUnit XML — качете доклада от проверката и грешките ще се появят в раздела Test на merge request.

.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

Проверка преди commit

За по-бърза обратна връзка изпълнявайте валидирането чрез hook преди commit. Така проблемите се откриват, преди изобщо да достигнат до CI, което спестява време за изпълнение на пайплайна и ускорява циклите за обратна връзка. Управлявайте hook-овете с 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
Hook-овете преди commit се изпълняват при всеки commit, затова трябва да бъдат бързи. Използвайте флага --locales, за да валидирате само локалите, променени в текущия commit, а не всички локали. Така при повечето проекти hook-ът се изпълнява за по-малко от 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