Skip to main content

Synkronisering af oversættelsesfiler: Hold i18n-nøgler synkroniseret på tværs af landestandarder

Hver gang en udvikler føjer en nøgle til kildelandestandarden, kommer 15 andre landestandardfiler ud af trit. Manglende nøgler viser rå stier til brugerne. Forældede nøgler spilder oversætternes tid og øger pakkestørrelsen. Automatisk synkronisering holder alt afstemt.

1

Synkroniseringsproblemet

Oversættelsesfiler glider hele tiden fra hinanden. En udvikler føjer 'settings.notifications.title' til en.json, men glemmer at føje den til de øvrige 15 landestandardfiler. En anden udvikler fjerner 'onboarding.welcome' fra koden, men lader den stå i alle landestandardfiler. En tredje udvikler omdøber 'user.name' til 'user.displayName' på engelsk, men ikke i de øvrige landestandarder. Efter nogle måneder er landestandardfilerne ikke længere ens: Nøgler mangler, er forældede eller stemmer ikke overens på tværs af landestandarder.

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
}
Manglende nøgler er værre end manglende oversættelser. En manglende oversættelse kan falde tilbage til kildesproget. En manglende nøgle medfører en kørselsfejl, viser en rå nøglesti til brugeren eller gengiver en tom streng. Synkronisering skal håndhæves, ikke overlades til håbet.
2

Registrering af manglende nøgler

En manglende nøgle er en nøgle, der findes i kildelandestandarden, men ikke i en mållandestandard. Det er det mest almindelige og mest skadelige synkroniseringsproblem – brugerne ser rå nøglestier som 'settings.notifications.title' i stedet for oversat tekst. i18n-validate registrerer manglende nøgler ved at sammenligne nøglestrukturen i hver landestandard med kilden.

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 flaget --check missing-keys for kun at fokusere på synkroniseringsproblemer. Brug --severity error til at lade manglende nøgler få CI til at fejle, så de bliver rettet før fletning.
3

Registrering af forældede nøgler

En forældet nøgle er en nøgle, der findes i oversættelsesfilerne, men ikke længere refereres i koden. Forældede nøgler spilder oversætternes tid (de oversætter strenge, som ingen ser), øger pakkestørrelsen og skaber forvirring under vedligeholdelsen. For at registrere forældede nøgler skal landestandardfilerne krydstjekkes mod referencer 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

Automatisering af synkronisering

Den mest effektive synkroniseringsstrategi kombinerer tre lag: 1) Pre-commit-hooks, der validerer synkroniseringen ved hvert commit. 2) Kontroller i CI-pipelinen, der blokerer fletninger med synkroniseringsproblemer. 3) Periodiske fulde revisioner, der finder afvigelser, som har samlet sig efter hotfixes og manuelle ændringer.

.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 af oversættelsesdækning

Oversættelsesdækningen er procentdelen af kildenøgler, der har oversættelser i hver mållandestandard. i18n-validate genererer en dækningsrapport, som viser procenttal pr. landestandard og fremhæver landestandarder, der er kommet bagud. Brug dækningstærskler i CI til at blokere fletninger, når dækningen falder under et acceptabelt niveau.

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
Angiv forskellige dækningstærskler for forskellige landestandarder. Dine primære landestandarder (de, fr, ja) kan kræve 100 % dækning, mens nyligt tilføjede landestandarder (th, vi) kan begynde på 80 % og gradvist hæve niveauet.

Prøv i18n Agent nu

Slip din oversættelsesfil her

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

eller klik for at vælge en fil

Målsprog

Kræver ingen tilmeldingEstimat med det samme

Ofte stillede spørgsmål om synkronisering af oversættelsesfiler