Cosa controlla i18n-validate?

Esegue 9 controlli: chiavi mancanti, chiavi in eccesso, segnaposto non validi, forme plurali errate, lingue mancanti, lingue orfane, errori di analisi, valori vuoti e stringhe non tradotte. Per ogni lingua, ciascun controllo può essere impostato come errore, avviso o disattivato.

Come si aggiunge la convalida delle traduzioni alla CI/CD?

Esegua 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' nella pipeline. Quando rileva errori, lo strumento termina con il codice 1, causando il normale esito negativo della CI. Usi l'output XML JUnit con le azioni dei reporter di test per inserire annotazioni direttamente nelle pull request.

Quali formati di file di traduzione sono supportati?

32 formati, tra cui JSON, YAML, XLIFF 1.2/2.0, XML Android, Strings iOS, Stringsdict iOS, cataloghi di stringhe Xcode, ARB Flutter, PO Gettext, Java Properties, RESX .NET, PHP/Laravel, CSV, Excel e altri. Lo strumento rileva automaticamente il formato dalle estensioni dei file.

Open Source CLI Tool

Validatore i18n

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

Analizzi i file di traduzione per rilevare chiavi mancanti, segnaposto non validi e incoerenze nei plurali. Un comando. 9 controlli. 32 formati. Senza configurazione.

9 checks 32 formats Zero config Native Rust binary

Il problema

I problemi di traduzione restano invisibili finché non li incontrano gli utenti. Una chiave mancante mostra un percorso non elaborato come "settings.billing.title" anziché il testo corretto. Un segnaposto non valido visualizza "{price}" come testo letterale anziché "9,99 $". Una forma plurale errata causa un arresto anomalo quando il conteggio è zero. Questi errori sfuggono alla revisione del codice perché nessuno confronta manualmente 15 file di lingua.

🔑

Missing keys

Blank text or key paths shown to users

🔗

Broken placeholders

{price} displays as literal text instead of $9.99

📁

Orphaned files

Outdated translations confuse the build system

💥

Malformed files

Runtime crashes when users switch languages

La maggior parte degli strumenti di convalida è specifica per un formato (solo JSON o solo YAML) e richiede codice di test personalizzato per ogni progetto. Spesso gli errori di traduzione vengono rilevati soltanto durante l'esecuzione, quando gli utenti vedono un'interfaccia non funzionante.

La soluzione

i18n-validate analizza tutti i file di traduzione in un unico passaggio. Rileva automaticamente la struttura delle directory e il formato dei file, confronta ogni lingua con quella di riferimento e indica con precisione cosa non va e dove. Senza plugin, configurazione o codice di test personalizzato.

Check	Severity	What it catches
missing-keys	error	Key exists in reference but is absent in a translation
extra-keys	error	Key exists in translation but not in the reference
placeholders	error	{price}, {{name}}, %s differ between languages
plural-structure	error	Plural forms are malformed or missing required categories
missing-languages	error	Expected language has no files or directory
orphaned-languages	error	Language files exist but are not in the expected list
parse-errors	error	File fails to parse (broken JSON, XML, YAML, etc.)
empty-values	warning	Key is present but the translation is an empty string
untranslated	warning	Translation is identical to the reference language

Terminal output

i18n-validate v0.1.0 — validating ./locales

  Reference: en (2 files: translation.json, apiTester.json)
  Languages: de, ja, fr, es, zh-Hans, pt-BR, ko (7 found, 7 expected)
  Layout   : directory (auto-detected)
  Formats  : i18next JSON (auto-detected)

────────────────────────────────────────────────

ERRORS (5)

  ✗ missing-keys │ translation.json
    Key "settings.billing.title"
      missing in: ja, ko

  ✗ placeholders │ translation.json
    Key "pricing.total" — expected: {price}, {currency}
      de:  found {price} only — missing {currency}

────────────────────────────────────────────────

WARNINGS (2)

  ⚠ empty-values │ translation.json
    Key "onboarding.step3.hint"
      empty in: de, fr

────────────────────────────────────────────────

  5 errors, 2 warnings across 7 languages
  ✗ Validation failed

Installazione

Installi lo strumento CLI a livello globale con il gestore di pacchetti preferito. Il pacchetto npm include un binario Rust nativo: non sono necessarie compilazione o dipendenze di runtime.

Terminal

npm install -g @i18n-agent/i18n-validate

Il pacchetto npm include un binario nativo precompilato per macOS, Linux e Windows. Non serve la toolchain Rust.

Utilizzo

Indichi allo strumento la directory delle lingue. Rileva automaticamente la lingua di riferimento, la struttura delle directory e il formato dei file. Per la maggior parte dei progetti non serve alcuna configurazione.

Terminal

# Zero-config validation
i18n-validate ./locales

# JSON output for scripting
i18n-validate ./locales --format json | jq '.summary'

# CI/CD with JUnit XML
i18n-validate ./locales --format junit -o i18n-report.xml

Integrazione CI/CD

Aggiunga la convalida delle traduzioni alla pipeline delle pull request. Lo strumento genera XML JUnit compatibile con i reporter di test di GitHub Actions, gli artefatti GitLab CI e qualsiasi sistema CI che supporti JUnit.

.github/workflows/validate-i18n.yml

name: Validate Translations
on:
  pull_request:
    paths: ['locales/**', 'public/locales/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate translations
        run: npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml

      - uses: dorny/test-reporter@v1
        if: always()
        with:
          name: i18n validation
          path: i18n-report.xml
          reporter: java-junit

The tool exits with code 1 when errors are found, so it naturally fails CI. Use --strict to also fail on warnings.

Formati supportati

Basato su i18n-convert, il validatore supporta 32 formati di file i18n senza configurazione aggiuntiva. Non servono plugin o impostazioni specifici per formato: lo strumento rileva automaticamente il formato dalle estensioni e dal contenuto dei file.

Mobile & Desktop

Android XML, Xcode String Catalog, iOS Strings, iOS Stringsdict, Flutter ARB, Qt Linguist

Web & Frameworks

Structured JSON, i18next JSON, JSON5, HJSON, YAML (Rails), YAML (Plain), JavaScript, TypeScript, PHP/Laravel, NEON

Standards & Exchange

XLIFF 1.2, XLIFF 2.0, Gettext PO, TMX, .NET RESX, Java Properties

Data & Other

CSV, Excel (.xlsx), TOML, INI, SRT Subtitles, Markdown, Plain Text

Configurazione

Per la maggior parte dei progetti funziona senza configurazione. Quando serve maggiore controllo, per modificare la gravità dei controlli, impostare le lingue previste o escludere quelle in corso di lavorazione, crei un file .i18n-validate.toml nella directory principale del progetto.

.i18n-validate.toml

# .i18n-validate.toml
ref = "en"
expect = ["de", "ja", "fr", "es", "zh-Hans", "pt-BR", "ko"]

[checks]
missing-keys = "error"
extra-keys = "error"
placeholders = "error"
empty-values = "warning"
untranslated = "warning"

[languages.ko]
missing-keys = "warning"    # Korean is WIP

[languages.ar]
skip = true                 # Exclude from validation