Skip to main content

Synkronisering av oversettelsesfiler: Hold i18n-nøkler synkronisert på tvers av språkvarianter

Hver gang en utvikler legger til en nøkkel i kildespråkvarianten, blir 15 andre lokaliseringsfiler usynkronisert. Manglende nøkler viser rå nøkkelstier til brukerne. Utdaterte nøkler sløser med oversetternes tid og øker pakkestørrelsen. Automatisk synkronisering holder alt samstemt.

1

Synkroniseringsproblemet

Oversettelsesfiler glir stadig fra hverandre. En utvikler legger til 'settings.notifications.title' i en.json, men glemmer å legge den til i de 15 andre lokaliseringsfilene. En annen utvikler fjerner 'onboarding.welcome' fra koden, men lar den stå i alle lokaliseringsfilene. En tredje utvikler endrer navnet fra 'user.name' til 'user.displayName' på engelsk, men ikke i de andre språkvariantene. I løpet av noen måneder avviker lokaliseringsfilene: Nøkler mangler, er utdaterte eller samsvarer ikke på tvers av språkvarianter.

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økler er verre enn manglende oversettelser. En manglende oversettelse kan falle tilbake på kildespråket. En manglende nøkkel fører til en kjøretidsfeil, viser en rå nøkkelsti til brukeren eller gjengir en tom streng. Synkronisering må håndheves, ikke overlates til håpet.
2

Oppdage manglende nøkler

En manglende nøkkel er en nøkkel som finnes i kildespråkvarianten, men ikke i en målspråkvariant. Dette er det vanligste og mest skadelige synkroniseringsproblemet – brukere ser rå nøkkelstier som 'settings.notifications.title' i stedet for oversatt tekst. i18n-validate oppdager manglende nøkler ved å sammenligne nøkkelstrukturen i hver språkvariant 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)
Kjør i18n-validate med flagget --check missing-keys for å fokusere spesielt på synkroniseringsproblemer. Bruk --severity error for å la manglende nøkler føre til at CI mislykkes, slik at de blir rettet før sammenslåing.
3

Oppdage utdaterte nøkler

En utdatert nøkkel er en nøkkel som finnes i oversettelsesfilene, men ikke lenger refereres til i koden. Utdaterte nøkler sløser med oversetternes tid (oversetterne oversetter strenger ingen ser), øker pakkestørrelsen og skaper forvirring under vedlikehold. For å oppdage utdaterte nøkler må lokaliseringsfilene kryssjekkes mot kodereferanser.

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

Automatisere synkronisering

Den mest effektive synkroniseringsstrategien kombinerer tre lag: 1) Kroker før innsjekking som validerer synkroniseringen ved hver innsjekking. 2) Kontroller i CI-prosessen som blokkerer sammenslåinger med synkroniseringsproblemer. 3) Regelmessige fullstendige gjennomganger som fanger opp avvik etter hurtigrettinger og manuelle endringer.

.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 oversettelsesdekning

Oversettelsesdekning er prosentandelen av kildenøklene som har oversettelser i hver målspråkvariant. i18n-validate genererer en dekningsrapport som viser prosentandelen for hver språkvariant og fremhever språkvarianter som blir hengende etter. Bruk dekningsterskler i CI for å blokkere sammenslåinger når dekningen faller under et akseptabelt 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
Angi forskjellige dekningsterskler for forskjellige språkvarianter. Primærspråkvariantene dine (de, fr, ja) kan kreve 100% dekning, mens nylig tilføyde språkvarianter (th, vi) kan starte på 80% og få terskelen hevet over tid.

Prøv i18n Agent nå

Slipp oversettelsesfilen din her

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

eller klikk for å bla gjennom

Målspråk

Ingen registrering krevesUmiddelbart estimat

Vanlige spørsmål om synkronisering av oversettelsesfiler