Skip to main content

Sincronização de ficheiros de tradução: mantenha as chaves de i18n sincronizadas entre regiões

Sempre que um programador acrescenta uma chave à região de origem, outros 15 ficheiros de região ficam dessincronizados. As chaves em falta mostram caminhos sem tratamento aos utilizadores. 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 ficheiros de tradução divergem constantemente. Um programador acrescenta 'settings.notifications.title' a en.json, mas esquece-se de a acrescentar aos outros 15 ficheiros de região. Outro programador retira 'onboarding.welcome' do código, mas deixa-a em todos os ficheiros de região. Um terceiro programador muda o nome de 'user.name' para 'user.displayName' em inglês, mas não nas outras regiões. Ao longo dos meses, os seus ficheiros de região divergem: há chaves em falta, desatualizadas ou sem correspondência entre regiões.

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 utilizador ou apresenta uma cadeia vazia. É necessário impor a sincronização, não esperar que aconteça.
2

Detetar chaves em falta

Uma chave em falta existe na região de origem, mas não numa região de destino. É o problema de sincronização mais comum e mais prejudicial: os utilizadores veem caminhos de chaves sem tratamento, como 'settings.notifications.title', em vez de texto traduzido. i18n-validate deteta chaves em falta comparando a estrutura de chaves de cada região 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

Detetar chaves desatualizadas

Uma chave desatualizada existe nos ficheiros de tradução, mas deixou de ser referenciada no código. As chaves desatualizadas desperdiçam o tempo dos tradutores (que traduzem cadeias que ninguém vê), aumentam o tamanho do pacote e criam confusão na manutenção. Para as detetar, é necessário cruzar os ficheiros de região 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 detetam 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 região de destino. i18n-validate gera um relatório de cobertura que mostra as percentagens por região e destaca as regiões 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 regiões diferentes. As suas regiões principais (de, fr, ja) podem exigir uma cobertura de 100%, enquanto regiões recém-adicionadas (th, vi) podem começar nos 80% e aumentar gradualmente.

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 sincronização de ficheiros de tradução