Skip to main content

Sincronización de archivos de traducción: mantenga sincronizadas las claves de i18n entre configuraciones regionales

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

1

El problema de sincronización

Los archivos de traducción se desincronizan constantemente. Un desarrollador añade 'settings.notifications.title' a en.json, pero olvida agregarla a los otros 15 archivos de configuración regional. Otro desarrollador elimina 'onboarding.welcome' del código, pero la deja en todos los archivos de configuración regional. Un tercer desarrollador cambia 'user.name' por 'user.displayName' en inglés, pero no en las demás configuraciones regionales. Con el paso de los meses, sus archivos de configuración regional divergen: faltan claves, sobran otras o no coinciden entre configuraciones regionales.

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 ausente puede recurrir al idioma de origen. Una clave ausente provoca un error en tiempo de ejecución, muestra una ruta de clave sin procesar al usuario o renderiza una cadena vacía. La sincronización debe exigirse, no dejarse al azar.
2

Detectar claves ausentes

Una clave ausente es una clave que existe en la configuración regional de origen, pero no en una de destino. Es el problema de sincronización más común y el más dañino: los usuarios ven rutas sin procesar como 'settings.notifications.title' en vez de texto traducido. i18n-validate las detecta comparando la estructura de claves de cada configuración regional con la de 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 problemas de sincronización. Utilice --severity error para que las claves ausentes hagan fallar CI y se corrijan antes de fusionar.
3

Detectar claves obsoletas

Una clave obsoleta es una clave que existe en los archivos de traducción, pero ya no se referencia en el código. Las claves obsoletas desperdician tiempo de traducción (se traducen cadenas que nadie ve), aumentan el tamaño del paquete y generan confusión en el mantenimiento. Para detectarlas, hay que cruzar los archivos de configuración regional con las referencias en el 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 de sincronización más eficaz combina tres capas: 1) hooks pre-commit que validan la sincronización en cada commit; 2) comprobaciones en el pipeline de CI que bloquean fusiones si hay problemas de sincronización; 3) auditorías completas periódicas que detectan desviaciones acumuladas por hotfixes 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 de traducción es el porcentaje de claves de origen que tienen traducción en cada configuración regional de destino. i18n-validate genera un informe de cobertura con porcentajes por configuración regional y destaca las que se están quedando atrás. Utilice umbrales de cobertura en CI para bloquear fusiones cuando la cobertura baje de un 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 de cobertura distintos por configuración regional. Sus configuraciones regionales principales (de, fr, ja) podrían requerir 100 % de cobertura, mientras que las recién agregadas (th, vi) podrían empezar en 80 % e ir aumentando con el tiempo.

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