Skip to main content

Sincronització de fitxers de traducció: mantingui sincronitzades les claus d'i18n entre configuracions regionals

Cada vegada que un desenvolupador afegeix una clau a la configuració regional d'origen, 15 fitxers més deixen d'estar sincronitzats. Les claus absents mostren rutes sense processar als usuaris. Les claus obsoletes malbaraten el temps dels traductors i augmenten la mida del paquet. La sincronització automatitzada ho manté tot alineat.

1

El problema de la sincronització

Els fitxers de traducció divergeixen constantment. Un desenvolupador afegeix 'settings.notifications.title' a en.json, però s'oblida d'afegir-la als altres 15 fitxers de configuració regional. Un altre desenvolupador elimina 'onboarding.welcome' del codi, però la deixa a tots els fitxers de configuració regional. Un tercer desenvolupador canvia el nom de 'user.name' per 'user.displayName' en anglès, però no en les altres configuracions regionals. Al cap dels mesos, els fitxers de configuració regional han divergit: hi ha claus absents, obsoletes o que no coincideixen entre configuracions regionals.

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
}
Les claus absents són pitjors que les traduccions absents. Una traducció absent pot recórrer a la llengua d'origen. Una clau absent provoca un error en temps d'execució, mostra a l'usuari una ruta de clau sense processar o renderitza una cadena buida. Cal imposar la sincronització, no confiar que es mantingui sola.
2

Detecció de claus absents

Una clau absent és una clau que existeix a la configuració regional d'origen, però no en una configuració regional de destinació. És el problema de sincronització més habitual i el més perjudicial: els usuaris veuen rutes de claus sense processar, com ara 'settings.notifications.title', en lloc del text traduït. i18n-validate detecta les claus absents comparant l'estructura de claus de cada configuració regional amb la d'origen.

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)
Executi i18n-validate amb el senyalador --check missing-keys per centrar-se específicament en els problemes de sincronització. Utilitzi --severity error perquè les claus absents facin fallar la CI i garantir que es corregeixin abans de fusionar els canvis.
3

Detecció de claus obsoletes

Una clau obsoleta és una clau que existeix als fitxers de traducció, però que ja no té cap referència al codi. Les claus obsoletes malbaraten el temps dels traductors —tradueixen cadenes que no veu ningú—, augmenten la mida del paquet i generen confusió durant el manteniment. Per detectar-les, cal contrastar els fitxers de configuració regional amb les referències del codi.

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

Automatització de la sincronització

L'estratègia de sincronització més eficaç combina tres capes: 1) Hooks de pre-commit que validen la sincronització en cada commit. 2) Comprovacions del pipeline de CI que bloquen les fusions amb problemes de sincronització. 3) Auditories completes periòdiques que detecten les divergències acumulades per correccions urgents i modificacions manuals.

.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

Informes de cobertura de traducció

La cobertura de traducció és el percentatge de claus d'origen que tenen traducció en cada configuració regional de destinació. i18n-validate genera un informe de cobertura amb els percentatges per configuració regional i destaca les que van endarrerides. Utilitzi llindars de cobertura en la CI per blocar les fusions quan la cobertura baixi d'un nivell acceptable.

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
Estableixi llindars de cobertura diferents per a cada configuració regional. Pot exigir una cobertura del 100% per a les configuracions regionals principals (de, fr, ja), mentre que les que s'acaben d'afegir (th, vi) poden començar amb un 80% i augmentar gradualment amb el temps.

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

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

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Preguntes freqüents sobre la sincronització de fitxers de traducció