O que verifica i18n-validate?

Executa 9 verificações: chaves em falta, chaves adicionais, marcadores danificados, formas plurais mal construídas, idiomas em falta, idiomas órfãos, erros de análise, valores vazios e cadeias por traduzir. Cada verificação pode ser definida por idioma como erro, aviso ou desativada.

Como adiciono a validação das traduções a CI/CD?

Execute 'npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml' no pipeline. A ferramenta termina com o código 1 quando encontra erros, o que faz CI falhar naturalmente. Utilize o resultado JUnit XML com ações de relatórios de testes para anotações em linha nos pedidos de integração.

Que formatos de ficheiro de tradução são compatíveis?

32 formatos, incluindo JSON, YAML, XLIFF 1.2/2.0, XML do Android, Strings e Stringsdict do iOS, catálogos de cadeias do Xcode, ARB do Flutter, PO Gettext, Java Properties, RESX do .NET, PHP/Laravel, CSV e Excel. A ferramenta deteta o formato através das extensões.

Open Source CLI Tool

Validador de i18n

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

Verifique ficheiros de tradução para encontrar chaves em falta, marcadores danificados e plurais inconsistentes. Um comando. 9 verificações. 32 formatos. Sem configuração.

9 checks 32 formats Zero config Native Rust binary

O problema

Os problemas de tradução são invisíveis até afetarem os utilizadores. Uma chave em falta mostra um caminho em bruto, como «settings.billing.title», em vez de texto real. Um marcador danificado apresenta «{price}» literalmente em vez de «9,99 €». Um plural mal formado provoca uma falha quando o número é zero. Estes erros escapam à revisão porque ninguém compara manualmente 15 ficheiros regionais.

🔑

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

A maioria dos validadores é específica de um formato —apenas JSON ou YAML— e exige código de teste personalizado em cada projeto. Muitas vezes, os erros só são detetados durante a execução, quando os utilizadores veem uma interface danificada.

A solução

i18n-validate analisa todos os seus ficheiros de tradução de uma só vez. Deteta automaticamente a disposição dos diretórios e o formato, compara cada idioma com a referência e indica exatamente o problema e o local. Sem plugins, configuração ou código de teste personalizado.

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

Instalação

Instale como ferramenta de CLI global através do seu gestor de pacotes preferido. O pacote npm inclui um binário Rust nativo, sem exigir compilação nem dependências durante a execução.

Terminal

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

O pacote npm inclui um binário nativo pré-compilado para macOS, Linux e Windows. Não precisa da cadeia de ferramentas Rust.

Utilização

Indique à ferramenta o diretório regional. Ela deteta automaticamente o idioma de referência, a disposição dos diretórios e o formato dos ficheiros. A maioria dos projetos não exige configuração.

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

Integração com CI/CD

Adicione a validação das traduções ao pipeline dos pedidos de integração. A ferramenta produz JUnit XML, que se integra nos relatórios de testes de GitHub Actions, nos artefactos de GitLab CI e em qualquer sistema de CI compatível com 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.

Formatos compatíveis

Com tecnologia i18n-convert, o validador é compatível de origem com 32 formatos de i18n. Não precisa de plugins nem de configurações específicas: a ferramenta deteta o formato pelas extensões e pelo conteúdo.

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

Configuração

Na maioria dos projetos, funciona sem configuração. Se precisar de controlo —substituir a gravidade das verificações, definir idiomas esperados ou excluir idiomas em curso—, crie um ficheiro .i18n-validate.toml na raiz do projeto.

.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