Skip to main content

Synchronisierung von Übersetzungsdateien: i18n-Schlüssel über Locales hinweg synchron halten

Jedes Mal, wenn ein neuer Schlüssel zur Ausgangs-Locale hinzukommt, geraten 15 weitere Locale-Dateien aus dem Takt. Fehlende Schlüssel zeigen unverarbeitete Pfade. Veraltete Schlüssel verschwenden Übersetzungszeit und Bundle-Größe. Automatisierte Synchronisierung hält alles ausgerichtet.

1

Das Synchronisierungsproblem

Übersetzungsdateien weichen ständig voneinander ab. Eine Person fügt settings.notifications.title zu en.json hinzu, vergisst aber die 15 anderen Locale-Dateien. Eine andere entfernt onboarding.welcome aus dem Code, lässt den Schlüssel jedoch in allen Locale-Dateien stehen. Eine dritte benennt user.name im Englischen in user.displayName um, aber nicht in anderen Locales. Über Monate driften Ihre Locale-Dateien auseinander: Schlüssel fehlen, sind veraltet oder stimmen nicht überein.

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
}
Fehlende Schlüssel sind problematischer als fehlende Übersetzungen. Eine fehlende Übersetzung kann auf die Ausgangssprache zurückfallen. Ein fehlender Schlüssel verursacht einen Laufzeitfehler, zeigt einen unverarbeiteten Schlüsselpfad oder rendert eine leere Zeichenfolge. Synchronisierung muss erzwungen werden und darf nicht dem Zufall überlassen bleiben.
2

Fehlende Schlüssel erkennen

Ein fehlender Schlüssel ist in der Ausgangs-Locale vorhanden, aber nicht in einer Ziel-Locale. Dies ist das häufigste und schädlichste Synchronisierungsproblem – Personen sehen unverarbeitete Schlüsselpfade wie settings.notifications.title statt übersetztem Text. i18n-validate erkennt fehlende Schlüssel, indem es die Schlüsselstruktur jeder Locale mit der Quelle vergleicht.

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)
Führen Sie i18n-validate mit der Option --check missing-keys aus, um sich auf Synchronisierungsprobleme zu konzentrieren. Lassen Sie mit --severity error fehlende Schlüssel in CI fehlschlagen, damit sie vor der Zusammenführung behoben werden.
3

Veraltete Schlüssel erkennen

Ein veralteter Schlüssel ist in Übersetzungsdateien vorhanden, wird im Code aber nicht mehr referenziert. Solche Schlüssel verschwenden Übersetzungszeit, weil unsichtbare Zeichenfolgen übersetzt werden, vergrößern Bundles und erschweren die Wartung. Ihre Erkennung erfordert den Abgleich von Locale-Dateien mit Codereferenzen.

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

Synchronisierung automatisieren

Die wirksamste Synchronisierungsstrategie kombiniert drei Ebenen: 1) Pre-Commit-Hooks, die bei jedem Commit synchronisieren. 2) CI-Pipeline-Prüfungen, die Zusammenführungen mit Synchronisierungsproblemen blockieren. 3) Regelmäßige vollständige Prüfungen, die durch Hotfixes und manuelle Bearbeitungen entstandene Abweichungen erkennen.

.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

Berichte zur Übersetzungsabdeckung

Die Übersetzungsabdeckung ist der Prozentsatz der Ausgangsschlüssel mit Übersetzung in jeder Ziel-Locale. i18n-validate erzeugt einen Abdeckungsbericht mit Prozentsätzen pro Locale und hebt zurückfallende Locales hervor. Blockieren Sie mit Abdeckungsschwellenwerten in CI Zusammenführungen, wenn die Abdeckung unter ein akzeptables Niveau sinkt.

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
Legen Sie für unterschiedliche Locales unterschiedliche Schwellenwerte fest. Ihre primären Locales (de, fr, ja) können 100 % erfordern, neu hinzugefügte Locales (th, vi) bei 80 % beginnen und den Wert schrittweise erhöhen.

i18n Agent jetzt testen

Legen Sie Ihre Übersetzungsdatei hier ab

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

oder zum Auswählen klicken

Zielsprachen

Keine Registrierung erforderlichSofortiges Angebot

Häufig gestellte Fragen zur Synchronisierung von Übersetzungsdateien