Skip to main content

Validarea traducerilor în CI: automatizați verificările i18n în fluxul dumneavoastră

Erorile de traducere sunt invizibile la examinarea codului. O cheie lipsă, un substituent deteriorat sau un plural format greșit nu apar în diferențele de cod. Validarea la nivel de CI le detectează înainte să ajungă în producție.

1

De ce scapă erorile de traducere la examinarea codului

Un dezvoltator adaugă 10 chei noi în en.json și actualizează codul funcționalității. Persoana care examinează PR-ul verifică codul și șirurile în engleză, apoi îl aprobă. Nimeni nu compară celelalte 14 fișiere de limbă. Trei erori ajung în producție: din de.json lipsesc 2 chei (utilizatorii vorbitori de germană văd căile brute ale cheilor), fr.json conține un substituent {count} deteriorat (utilizatorii vorbitori de franceză văd textul literal {count}), iar ja.json conține un plural ICU format greșit (utilizatorii vorbitori de japoneză întâmpină o oprire a aplicației). Aceste probleme pot fi prevenite printr-o verificare CI de 30 de secunde.

Erorile de traducere au o proprietate unică: sunt invizibile pentru dezvoltator și pentru persoana care examinează codul și devin vizibile numai utilizatorilor unei anumite limbi. Validarea CI este singura metodă fiabilă de a le detecta înainte de producție.
2

Instalați i18n-validate

Adăugați i18n-validate în proiect drept dependență de dezvoltare. Acceptă direct formatele JSON, YAML, PO, XLIFF și ARB, fără să fie necesară configurarea pentru utilizarea de bază.

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

Integrarea cu GitHub Actions

Adăugați i18n-validate ca etapă în fluxul solicitărilor pull. Instrumentul se încheie cu codul 1 când găsește erori, ceea ce face ca verificarea PR-ului să eșueze. Folosiți rezultatul JUnit XML împreună cu o acțiune de raportare a testelor pentru a obține adnotări direct în diferențele PR-ului.

.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
Fixați versiunea i18n-validate în flux pentru a evita întreruperile neașteptate provocate de reguli noi de validare. Folosiți @latest numai în mediul de dezvoltare.
4

Integrarea cu GitLab CI

Adăugați o sarcină de validare a traducerilor în fluxul .gitlab-ci.yml. GitLab acceptă nativ artefactele JUnit XML: încărcați raportul de validare, iar erorile vor apărea în fila Test a solicitării de îmbinare.

.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

Pentru feedback mai rapid, executați validarea printr-un hook pre-commit. Astfel detectați problemele înainte ca acestea să ajungă în CI, economisiți timpul fluxului și scurtați ciclurile de feedback. Folosiți Husky (JS) sau pre-commit (Python) pentru gestionarea hook-urilor.

.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-urile pre-commit se execută la fiecare commit, așadar trebuie să rămână rapide. Folosiți opțiunea --locales pentru a valida numai limbile modificate în commitul curent, nu toate limbile. Astfel, pentru majoritatea proiectelor, hook-ul se execută în mai puțin de 2 secunde.
6

Configurare și niveluri de severitate

Personalizați comportamentul validării prin fișierul de configurare .i18n-validate.toml. Setați severitatea verificării (error, warning, off) pentru fiecare regulă, definiți limbile așteptate, excludeți limbile în curs de elaborare și configurați formatul rezultatului. În CI, numai erorile opresc fluxul; avertismentele apar în raport, dar nu îl blochează.

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
}

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Întrebări frecvente despre validarea traducerilor în CI