Skip to main content

Synchronisation des fichiers de traduction : gardez les clés i18n synchronisées entre les langues

À chaque fois qu'un développeur ajoute une clé à la langue source, 15 autres fichiers de langue se désynchronisent. Les clés manquantes affichent des chemins bruts aux utilisateurs. Les clés obsolètes gaspillent le temps des traducteurs et la taille du bundle. La synchronisation automatisée garde tout aligné.

1

Le problème de synchronisation

Les fichiers de traduction divergent en permanence. Un développeur ajoute « settings.notifications.title » à en.json mais oublie de l'ajouter aux 15 autres fichiers de langue. Un autre développeur retire « onboarding.welcome » du code mais le laisse dans tous les fichiers de langue. Un troisième développeur renomme « user.name » en « user.displayName » en anglais mais pas dans les autres langues. Au fil des mois, vos fichiers de langue divergent : des clés manquent, sont obsolètes ou ne correspondent plus d'une langue à l'autre.

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 clés manquantes sont pires que les traductions manquantes. Une traduction manquante peut se replier sur la langue source. Une clé manquante provoque une erreur d'exécution, affiche un chemin de clé brut à l'utilisateur, ou génère une chaîne vide. La synchronisation doit être imposée, pas simplement espérée.
2

Détecter les clés manquantes

Une clé manquante est une clé qui existe dans la langue source mais pas dans une langue cible. C'est le problème de synchronisation le plus courant et le plus dommageable — les utilisateurs voient des chemins de clé bruts comme « settings.notifications.title » au lieu du texte traduit. i18n-validate détecte les clés manquantes en comparant la structure des clés de chaque langue à celle de la source.

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)
Exécutez i18n-validate avec l'option --check missing-keys pour vous concentrer spécifiquement sur les problèmes de synchronisation. Utilisez --severity error pour que les clés manquantes fassent échouer l'intégration continue, garantissant qu'elles sont corrigées avant la fusion.
3

Détecter les clés obsolètes

Une clé obsolète est une clé qui existe dans les fichiers de traduction mais qui n'est plus référencée dans le code. Les clés obsolètes font perdre du temps aux traducteurs (ils traduisent des chaînes que personne ne voit), augmentent la taille du bundle et créent une confusion dans la maintenance. Détecter les clés obsolètes nécessite de croiser les fichiers de langue avec les références du code.

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

Automatiser la synchronisation

La stratégie de synchronisation la plus efficace combine trois niveaux : 1) des hooks pre-commit qui valident la synchronisation à chaque commit ; 2) des contrôles dans le pipeline CI qui bloquent les fusions en cas de problème de synchronisation ; 3) des audits complets périodiques qui détectent les dérives accumulées lors des correctifs urgents et des modifications manuelles.

.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

Rapports de couverture de traduction

La couverture de traduction correspond au pourcentage de clés source disposant d'une traduction dans chaque langue cible. i18n-validate génère un rapport de couverture indiquant les pourcentages par langue et mettant en évidence celles qui prennent du retard. Utilisez des seuils de couverture dans votre CI pour bloquer les fusions lorsque la couverture descend sous un niveau 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
Définissez des seuils de couverture différents selon les langues. Vos langues principales (de, fr, ja) peuvent exiger une couverture de 100 %, tandis que les langues récemment ajoutées (th, vi) peuvent démarrer à 80 % et progresser au fil du temps.

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

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

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

FAQ sur la synchronisation des fichiers de traduction