Skip to main content

Sincronização de arquivos de tradução: mantenha as chaves de i18n sincronizadas entre localidades

Sempre que um desenvolvedor adiciona uma chave à localidade de origem, outros 15 arquivos de localidade ficam dessincronizados. As chaves em falta mostram caminhos sem tratamento aos usuários. As chaves desatualizadas desperdiçam o tempo dos tradutores e aumentam o tamanho do pacote. A sincronização automatizada mantém tudo alinhado.

1

O problema da sincronização

Os arquivos de tradução divergem constantemente. Um desenvolvedor adiciona 'settings.notifications.title' a en.json, mas se esquece de a adicionar aos outros 15 arquivos de localidade. Outro desenvolvedor retira 'onboarding.welcome' do código, mas a deixa em todos os arquivos de localidade. Um terceiro desenvolvedor muda o nome de 'user.name' para 'user.displayName' em inglês, mas não nas outras localidades. Ao longo dos meses, seus arquivos de localidade divergem: há chaves em falta, desatualizadas ou sem correspondência entre localidades.

The drift problem
// The problem: translation files drift out of sync

// Developer adds a new feature with new keys:
// en.json (source of truth)
{
  "nav.home": "Home",
  "nav.about": "About",
  "nav.pricing": "Pricing",     // NEW
  "nav.changelog": "Changelog"  // NEW
}

// de.json (out of sync - missing new keys)
{
  "nav.home": "Startseite",
  "nav.about": "Über uns"
  // nav.pricing - MISSING
  // nav.changelog - MISSING
}

// de.json also has stale keys from deleted features:
{
  "nav.home": "Startseite",
  "nav.about": "Über uns",
  "nav.legacy_page": "Alte Seite"  // STALE - removed from en.json
}
As chaves em falta são piores do que traduções em falta. Uma tradução em falta pode recorrer ao idioma de origem. Uma chave em falta causa um erro de tempo de execução, mostra um caminho de chave sem tratamento ao usuário ou apresenta uma string vazia. É necessário impor a sincronização, não esperar que aconteça.
2

Detectar chaves em falta

Uma chave em falta existe na localidade de origem, mas não em uma localidade de destino. É o problema de sincronização mais comum e mais prejudicial: os usuários veem caminhos de chaves sem tratamento, como 'settings.notifications.title', em vez de texto traduzido. i18n-validate detecta chaves em falta comparando a estrutura de chaves de cada localidade com a origem.

Terminal
# Detect missing and stale keys
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json'

# Output:
# locales/de.json:
#   Missing keys (2):
#     - nav.pricing
#     - nav.changelog
#   Stale keys (1):
#     - nav.legacy_page
#   Coverage: 66.7% (2/3 keys)
#
# locales/ja.json:
#   Missing keys (5):
#     - nav.pricing
#     - nav.changelog
#     - settings.theme
#     - settings.language
#     - settings.notifications
#   Coverage: 50.0% (5/10 keys)
Execute i18n-validate com a opção --check missing-keys para se concentrar especificamente nos problemas de sincronização. Utilize --severity error para que as chaves em falta façam falhar CI e sejam corrigidas antes da integração.
3

Detectar chaves desatualizadas

Uma chave desatualizada existe nos arquivos de tradução, mas deixou de ser referenciada no código. As chaves desatualizadas desperdiçam o tempo dos tradutores (que traduzem strings que ninguém vê), aumentam o tamanho do pacote e criam confusão na manutenção. Para as detectar, é necessário cruzar os arquivos de localidade com as referências no código.

Terminal
# Step 1: Check which files are out of sync
npx i18n-validate sync --source locales/en.json --targets 'locales/*.json'

# Step 2: Auto-fill missing keys with source values (as placeholders)
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --fill-missing \
  --fill-value "[NEEDS TRANSLATION] {{source}}"

# Step 3: Remove stale keys no longer in source
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --remove-stale

# Step 4: Sort keys to match source order (cleaner diffs)
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --sort-keys

# All at once:
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --fill-missing \
  --remove-stale \
  --sort-keys
4

Automatizar a sincronização

A estratégia de sincronização mais eficaz combina três camadas: 1) hooks de pré-confirmação que validam a sincronização em cada confirmação; 2) verificações no pipeline de CI que bloqueiam integrações com problemas de sincronização; 3) auditorias completas periódicas que detectam divergências acumuladas por correções urgentes e edições manuais.

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Check if source locale file changed
SOURCE_CHANGED=$(git diff --cached --name-only | grep -c 'locales/en.json')

if [ "$SOURCE_CHANGED" -gt 0 ]; then
  echo "Source locale changed - checking sync..."

  npx i18n-validate sync \
    --source locales/en.json \
    --targets 'locales/*.json' \
    --fail-on-missing \
    --min-coverage 90

  if [ $? -ne 0 ]; then
    echo ""
    echo "Translation files are out of sync!"
    echo "Run: npx i18n-validate sync --fill-missing"
    exit 1
  fi
fi
.github/workflows/i18n-sync.yml
# .github/workflows/i18n-sync.yml
name: Translation Sync Check

on:
  pull_request:
    paths:
      - 'locales/**'

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

      - name: Check translation sync
        run: npx i18n-validate sync \
          --source locales/en.json \
          --targets 'locales/*.json' \
          --fail-on-missing \
          --min-coverage 95

      - name: Comment on PR if out of sync
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Translation files are out of sync. Please run npx i18n-validate sync --fill-missing and commit.'
            })
5

Relatórios de cobertura das traduções

A cobertura das traduções é a percentagem de chaves de origem que têm traduções em cada localidade de destino. i18n-validate gera um relatório de cobertura que mostra as percentagens por localidade e destaca as localidades atrasadas. Utilize limites de cobertura em CI para bloquear integrações quando a cobertura ficar abaixo de um nível aceitável.

Namespace-based sync
// Split large translation files by feature/namespace
// locales/
// ├── en/
// │   ├── common.json      (nav, footer, errors)
// │   ├── auth.json         (login, register, reset)
// │   ├── dashboard.json    (dashboard-specific)
// │   └── settings.json     (settings page)
// ├── de/
// │   ├── common.json
// │   ├── auth.json
// │   ├── dashboard.json
// │   └── settings.json

// Sync with namespace support:
npx i18n-validate sync \
  --source 'locales/en/*.json' \
  --targets 'locales/*/%.json' \
  --namespace-pattern '{locale}/{namespace}.json'

// Benefits:
// - Smaller files, easier to review
// - Feature teams own their translations
// - Lazy-load only needed namespaces
// - Parallel translation workflows
Defina limites de cobertura diferentes para localidades diferentes. Suas localidades principais (de, fr, ja) podem exigir uma cobertura de 100%, enquanto localidades recém-adicionadas (th, vi) podem começar com 80% e aumentar gradualmente.

Experimente já o i18n Agent

Solte aqui seu arquivo de tradução

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

ou clique para selecionar

Idiomas de destino

Sem cadastroEstimativa imediata

Perguntas frequentes sobre sincronização de arquivos de tradução