Skip to main content

Walidacja tłumaczeń w CI: automatyzuj kontrole i18n w pipeline

Błędów tłumaczeń nie widać podczas przeglądu kodu. Brakujący klucz, uszkodzony symbol zastępczy czy błędna forma liczby mnogiej nie pojawiają się w różnicy zmian. Walidacja na poziomie CI wykrywa je przed wdrożeniem produkcyjnym.

1

Dlaczego błędy tłumaczeń przechodzą przegląd kodu

Programista dodaje 10 nowych kluczy do en.json i aktualizuje kod funkcji. Osoba przeglądająca PR sprawdza kod oraz angielskie ciągi i zatwierdza zmiany. Nikt nie porównuje 14 pozostałych plików językowych. Na produkcję trafiają trzy błędy: w de.json brakuje 2 kluczy, więc niemieccy użytkownicy widzą surowe ścieżki; fr.json ma uszkodzony symbol zastępczy {count}, więc francuscy użytkownicy widzą dosłownie {count}; ja.json zawiera błędną formę liczby mnogiej ICU, przez co japońskim użytkownikom aplikacja ulega awarii. Wszystkim tym problemom zapobiega 30-sekundowa kontrola CI.

Błędy tłumaczeń mają wyjątkową cechę: nie widzi ich programista ani osoba przeglądająca kod, lecz wyłącznie użytkownicy konkretnego języka. Walidacja CI to jedyny niezawodny sposób, aby wykryć je przed produkcją.
2

Zainstaluj i18n-validate

Dodaj i18n-validate do projektu jako zależność deweloperską. Od razu obsługuje formaty JSON, YAML, PO, XLIFF i ARB — podstawowe użycie nie wymaga konfiguracji.

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

Integracja z GitHub Actions

Dodaj i18n-validate jako krok w procesie pull requestu. Po wykryciu błędów narzędzie kończy działanie z kodem 1, przez co kontrola PR kończy się niepowodzeniem. Użyj wyniku JUnit XML z modułem raportującym testy, aby uzyskać adnotacje bezpośrednio w różnicy zmian 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
Przypnij wersję i18n-validate w procesie, aby uniknąć niespodziewanych awarii po dodaniu nowych reguł walidacji. Używaj @latest wyłącznie podczas programowania.
4

Integracja z GitLab CI

Dodaj zadanie walidacji tłumaczeń do pipeline .gitlab-ci.yml. GitLab natywnie obsługuje artefakty JUnit XML — prześlij raport walidacji, a błędy pojawią się na karcie Testy żądania scalenia.

.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

Hook pre-commit

Aby szybciej otrzymywać informacje zwrotne, uruchamiaj walidację jako hook pre-commit. Wykrywa problemy, zanim dotrą do CI, oszczędzając czas pipeline i skracając pętlę informacji zwrotnej. Do zarządzania hookami użyj Husky (JS) lub 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
Hooki pre-commit uruchamiają się przy każdym zatwierdzeniu, dlatego muszą działać szybko. Użyj flagi --locales, aby walidować tylko języki zmienione w bieżącym zatwierdzeniu zamiast wszystkich. W większości projektów skraca to wykonanie hooka do mniej niż 2 sekund.
6

Konfiguracja i poziomy ważności

Dostosuj działanie walidacji za pomocą pliku konfiguracyjnego .i18n-validate.toml. Ustaw ważność kontroli (error, warning, off) dla każdej reguły, zdefiniuj oczekiwane języki, wyklucz języki w toku i skonfiguruj format wyniku. W CI tylko błędy powodują niepowodzenie pipeline — ostrzeżenia pojawiają się w raporcie, ale niczego nie blokują.

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
}

Wypróbuj i18n Agent

Upuść tutaj plik tłumaczenia

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

lub kliknij, aby go wybrać

Języki docelowe

Rejestracja nie jest wymaganaNatychmiastowa wycena

Najczęstsze pytania o walidację tłumaczeń w CI