Skip to main content

Validação de traduções em CI: automatize as verificações de i18n no seu pipeline

Os erros de tradução são invisíveis na revisão de código. Uma chave em falta, um marcador de posição danificado ou um plural malformado não aparecem numa diferença. A validação ao nível de CI deteta-os antes de chegarem à produção.

1

Porque escapam os erros de tradução à revisão de código

Um programador acrescenta 10 chaves novas a en.json e atualiza o código da funcionalidade. O revisor do PR verifica o código e as cadeias inglesas e aprova. Ninguém compara os outros 14 ficheiros de região. Três erros chegam à produção: faltam 2 chaves em de.json (os utilizadores alemães veem caminhos de chaves sem tratamento), fr.json tem um marcador de posição {count} danificado (os utilizadores franceses veem literalmente {count}) e ja.json tem um plural ICU malformado (os utilizadores japoneses veem uma falha). Estes erros podem ser evitados com uma verificação de CI de 30 segundos.

Os erros de tradução têm uma propriedade única: são invisíveis para o programador e o revisor e só são visíveis para os utilizadores de uma região específica. A validação em CI é a única forma fiável de os detetar antes da produção.
2

Instalar i18n-validate

Acrescente i18n-validate ao seu projeto como dependência de desenvolvimento. Aceita os formatos JSON, YAML, PO, XLIFF e ARB sem configuração adicional; não é necessária configuração para a utilização básica.

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

Integração com GitHub Actions

Acrescente i18n-validate como passo no seu fluxo de trabalho de pedidos de integração. A ferramenta termina com o código 1 quando encontra erros, o que faz falhar a verificação do PR. Utilize a saída XML JUnit com uma ação de relatórios de testes para obter anotações incorporadas diretamente na diferença do 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
Fixe a versão de i18n-validate no seu fluxo de trabalho para evitar falhas inesperadas devido a novas regras de validação. Utilize @latest apenas no desenvolvimento.
4

Integração com GitLab CI

Acrescente uma tarefa de validação de traduções ao seu pipeline .gitlab-ci.yml. GitLab aceita nativamente artefactos XML JUnit: carregue o relatório de validação e os erros aparecerão no separador Test do pedido de integração.

.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 de pré-confirmação

Para obter feedback mais rápido, execute a validação como hook de pré-confirmação. Isto deteta os problemas antes de chegarem a CI, poupa tempo de pipeline e reduz os ciclos de feedback. Utilize Husky (JS) ou pre-commit (Python) para gerir os hooks.

.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
Os hooks de pré-confirmação são executados em cada confirmação, por isso mantenha-os rápidos. Utilize a opção --locales para validar apenas as regiões alteradas na confirmação atual, em vez de todas. Assim, a execução do hook demora menos de 2 segundos na maioria dos projetos.
6

Configuração e níveis de gravidade

Personalize o comportamento da validação com um ficheiro de configuração .i18n-validate.toml. Defina a gravidade da verificação (error, warning, off) por regra, indique os idiomas esperados, exclua regiões em curso e configure o formato de saída. Em CI, apenas os erros fazem falhar o pipeline; os avisos aparecem no relatório, mas não bloqueiam.

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
}

Experimente já o i18n Agent

Largue aqui o seu ficheiro de tradução

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

ou clique para selecionar

Idiomas de destino

Sem registoEstimativa imediata

Perguntas frequentes sobre validação de traduções em CI