Skip to main content

Sincronización de archivos de traducción: mantenga las claves alineadas entre regiones

Cada vez que un desarrollador añade una clave al origen, otros 15 archivos quedan desincronizados. Las ausentes muestran rutas a los usuarios. Las obsoletas desperdician tiempo de traducción y tamaño del paquete. La sincronización automatizada lo mantiene todo alineado.

1

El problema de sincronización

Los archivos se desvían constantemente. Un desarrollador añade 'settings.notifications.title' a en.json, pero olvida los otros 15. Otro elimina 'onboarding.welcome' del código, pero la deja en todos los archivos. Un tercero cambia 'user.name' por 'user.displayName' en inglés, no en los demás. Con los meses, divergen: faltan claves, sobran otras o no coinciden entre regiones.

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
}
Las claves ausentes son peores que las traducciones ausentes. Una traducción puede recurrir al idioma de origen. Una clave ausente provoca un error durante la ejecución, muestra su ruta al usuario o renderiza una cadena vacía. La sincronización debe exigirse, no dejarse al azar.
2

Detectar claves ausentes

Una clave ausente existe en la región de origen, pero no en una de destino. Es el problema más habitual y dañino: los usuarios ven rutas como 'settings.notifications.title' en vez de texto. i18n-validate las detecta comparando la estructura de cada región con el 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)
Ejecute i18n-validate con --check missing-keys para centrarse en la sincronización. Utilice --severity error para que las claves ausentes hagan fallar CI y deban corregirse antes de fusionar.
3

Detectar claves obsoletas

Una clave obsoleta existe en los archivos, pero ya no se referencia en el código. Desperdicia tiempo —se traducen cadenas que nadie ve—, aumenta el paquete y confunde el mantenimiento. Detectarla exige cruzar los archivos con las referencias del 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 la sincronización

La estrategia más eficaz combina tres capas: 1) hooks pre-commit que validan cada confirmación; 2) comprobaciones de CI que bloquean fusiones con problemas; 3) auditorías completas periódicas que detectan desviaciones acumuladas por correcciones rápidas y ediciones manuales.

.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ón

La cobertura es el porcentaje de claves de origen traducidas en cada región. i18n-validate genera un informe con los porcentajes y destaca las que se quedan atrás. Utilice umbrales en CI para bloquear fusiones cuando bajen del nivel aceptable.

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 umbrales distintos por región. Las principales —de, fr y ja— pueden exigir un 100 %, mientras las nuevas —th y vi— pueden empezar en el 80 % y aumentar gradualmente.

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

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

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Preguntas frecuentes sobre sincronización de archivos de traducción