Skip to main content

Synkronisering av översättningsfiler: Håll i18n-nycklar synkroniserade mellan språkversioner

Varje gång en utvecklare lägger till en nyckel i källspråket blir 15 andra språkfiler osynkroniserade. Saknade nycklar visar obearbetade sökvägar för användarna. Inaktuella nycklar tar översättarnas tid och ökar paketstorleken. Automatisk synkronisering håller allt samordnat.

1

Synkroniseringsproblemet

Översättningsfiler glider ständigt isär. En utvecklare lägger till 'settings.notifications.title' i en.json men glömmer att lägga till den i de 15 andra språkfilerna. En annan utvecklare tar bort 'onboarding.welcome' från koden men lämnar kvar den i alla språkfiler. En tredje utvecklare byter namn på 'user.name' till 'user.displayName' på engelska men inte i de andra språkversionerna. Efter några månader skiljer sig språkfilerna åt: nycklar saknas, är inaktuella eller matchar inte mellan språkversionerna.

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
}
Saknade nycklar är värre än saknade översättningar. En saknad översättning kan använda källspråket som reserv. En saknad nyckel orsakar ett körningsfel, visar en obearbetad nyckelsökväg för användaren eller renderar en tom sträng. Synkronisering måste upprätthållas systematiskt.
2

Identifiera saknade nycklar

En saknad nyckel är en nyckel som finns i källspråket men inte i ett målspråk. Det är det vanligaste och mest skadliga synkroniseringsproblemet – användarna ser obearbetade nyckelsökvägar som 'settings.notifications.title' i stället för översatt text. i18n-validate hittar saknade nycklar genom att jämföra nyckelstrukturen i varje språkversion med källan.

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)
Kör i18n-validate med flaggan --check missing-keys för att fokusera på synkroniseringsproblem. Använd --severity error för att låta saknade nycklar stoppa CI och se till att de åtgärdas före sammanslagning.
3

Identifiera inaktuella nycklar

En inaktuell nyckel finns i översättningsfilerna men används inte längre i koden. Sådana nycklar tar översättarnas tid (de översätter strängar som ingen ser), ökar paketstorleken och skapar förvirring vid underhåll. För att hitta dem måste språkfilerna jämföras med referenserna i koden.

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

Automatisera synkroniseringen

En effektiv synkroniseringsstrategi kombinerar tre lager: 1) Pre-commit-hooks som validerar synkroniseringen vid varje commit. 2) Kontroller i CI-pipelinen som blockerar sammanslagningar med synkroniseringsproblem. 3) Regelbundna fullständiga granskningar som hittar avvikelser efter snabbkorrigeringar och manuella ändringar.

.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

Rapportering av översättningstäckning

Översättningstäckning är den procentandel av källans nycklar som har översättningar i varje målspråk. i18n-validate genererar en täckningsrapport som visar procentandelen per språkversion och framhäver språkversioner som halkar efter. Använd täckningströsklar i CI för att blockera sammanslagningar när täckningen sjunker under en godtagbar nivå.

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
Ange olika täckningströsklar för olika språkversioner. Dina viktigaste språkversioner (de, fr, ja) kan kräva 100 % täckning medan nytillagda språkversioner (th, vi) kan börja på 80 % och höja tröskeln med tiden.

Prova i18n Agent nu

Släpp din översättningsfil här

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

eller klicka för att välja en fil

Målspråk

Ingen registrering krävsPrisuppskattning direkt

Vanliga frågor om synkronisering av översättningsfiler