Cosa controlla la convalida delle traduzioni nella CI?

Controlla chiavi mancanti (presenti nella lingua di origine ma assenti in quella di destinazione), chiavi in eccesso (presenti nella destinazione ma non nell'origine), segnaposto non validi ({name} nell'origine ma {nome} nella destinazione), plurali ICU errati, valori vuoti, stringhe non tradotte (destinazione identica all'origine) ed errori di analisi nei file di traduzione.

Quali formati di file di traduzione sono supportati?

i18n-validate supporta più di 32 formati, tra cui JSON, YAML, XLIFF, XML Android, Strings/Stringsdict iOS, ARB Flutter, PO Gettext, Java Properties, RESX .NET, PHP/Laravel, CSV e altri. Il formato viene rilevato automaticamente dalle estensioni dei file.

Quanto tempo richiede la convalida nella CI?

In genere, meno di 5 secondi per la maggior parte dei progetti, fino a 20 lingue e 5.000 chiavi per lingua. Lo strumento è un binario Rust nativo, quindi si avvia istantaneamente ed elabora i file in parallelo. Anche i progetti di grandi dimensioni con più di 50 lingue terminano in meno di 15 secondi.

La codebase contiene centinaia di problemi di traduzione esistenti. Da dove si inizia?

Inizi impostando tutti i controlli su 'warning' in .i18n-validate.toml. I problemi verranno segnalati senza causare il fallimento della CI. Corregga prima quelli critici, come chiavi mancanti e segnaposto non validi, quindi promuova un controllo alla volta a 'error'. Usi il flag --locales negli hook pre-commit per convalidare soltanto i file modificati.

Come si ottengono annotazioni direttamente nelle pull request dai risultati della convalida?

Esegua i18n-validate con --format junit -o report.xml, quindi usi un'azione reporter di test (dorny/test-reporter per GitHub, artefatti JUnit nativi per GitLab). Gli errori di convalida appaiono come annotazioni direttamente nel diff della pull request, indicando file, chiave e problema esatti.

Convalida delle traduzioni nella CI: automatizzare i controlli i18n nella pipeline

Name: i18n Agent
Price: 0.01 EUR
Author: i18n Agent

Gli errori di traduzione sono invisibili durante la revisione del codice. Una chiave mancante, un segnaposto non valido o un plurale errato non appaiono nel diff. La convalida a livello di CI li rileva prima che raggiungano la produzione.

Perché gli errori di traduzione sfuggono alla revisione del codice

Uno sviluppatore aggiunge 10 nuove chiavi a en.json e aggiorna il codice della funzionalità. Il revisore della pull request controlla il codice, verifica le stringhe inglesi e approva. Nessuno confronta gli altri 14 file di lingua. Tre errori raggiungono la produzione: a de.json mancano 2 chiavi (gli utenti tedeschi vedono i percorsi non elaborati), fr.json contiene un segnaposto {count} non valido (gli utenti francesi vedono letteralmente {count}) e ja.json presenta un plurale ICU errato (gli utenti giapponesi subiscono un arresto anomalo). Un controllo CI di 30 secondi può evitare tutti questi problemi.

Gli errori di traduzione hanno una caratteristica unica: sono invisibili allo sviluppatore e al revisore e risultano visibili soltanto agli utenti di una lingua specifica. La convalida CI è l'unico modo affidabile per rilevarli prima della produzione.

Installare i18n-validate

Aggiunga i18n-validate al progetto come dipendenza di sviluppo. Supporta i formati JSON, YAML, PO, XLIFF e ARB senza configurazione aggiuntiva: per l'uso di base non serve alcuna impostazione.

Terminal

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

Integrazione con GitHub Actions

Aggiunga i18n-validate come passaggio nel flusso delle pull request. Quando rileva errori, lo strumento termina con il codice 1 e il controllo della pull request non riesce. Usi l'output XML JUnit con un'azione reporter di test per ottenere annotazioni direttamente nel diff della pull request.

.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

Fissi la versione di i18n-validate nel flusso per evitare interruzioni impreviste dovute a nuove regole di convalida. Usi @latest soltanto durante lo sviluppo.

Integrazione con GitLab CI

Aggiunga un processo di convalida delle traduzioni alla pipeline .gitlab-ci.yml. GitLab supporta in modo nativo gli artefatti XML JUnit: invii il rapporto di convalida e gli errori appariranno nella scheda Test della 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/**/*

Hook pre-commit

Per ricevere riscontri più rapidamente, esegua la convalida come hook pre-commit. In questo modo rileva i problemi prima che raggiungano la CI, risparmiando tempo nella pipeline e accorciando i cicli di feedback. Usi Husky (JS) o pre-commit (Python) per gestire gli hook.

.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

Gli hook pre-commit vengono eseguiti a ogni commit, quindi devono essere rapidi. Usi il flag --locales per convalidare soltanto le lingue modificate nel commit corrente, anziché tutte. Per la maggior parte dei progetti, l'esecuzione dell'hook rimarrà inferiore a 2 secondi.

Configurazione e livelli di gravità

Personalizzi il comportamento della convalida con un file di configurazione .i18n-validate.toml. Imposti la gravità dei controlli (errore, avviso, disattivato) per ogni regola, definisca le lingue previste, escluda quelle in corso di lavorazione e configuri il formato di output. Nella CI, soltanto gli errori causano il fallimento della pipeline; gli avvisi appaiono nel rapporto, ma non bloccano.

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
}

Provi subito i18n Agent

Trascinare qui il file di traduzione

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

oppure fare clic per selezionarlo

Lingue di destinazione

Nessuna registrazione richiestaPreventivo immediato