Skip to main content

Sinkronizacija datoteka prijevoda: uskladite i18n ključeve u svim lokalizacijama

Svaki put kada programer doda ključ u izvornu lokalizaciju, preostalih 15 datoteka više nije usklađeno. Ključevi koji nedostaju korisnicima prikazuju sirove putanje. Zastarjeli ključevi troše vrijeme prevoditelja i povećavaju paket. Automatizirana sinkronizacija održava sve usklađenim.

1

Problem sinkronizacije

Datoteke prijevoda neprestano se razilaze. Programer doda 'settings.notifications.title' u en.json, ali ga zaboravi dodati u preostalih 15 datoteka lokalizacije. Drugi programer ukloni 'onboarding.welcome' iz koda, ali ga ostavi u svim datotekama. Treći u engleskom preimenuje 'user.name' u 'user.displayName', ali ne i u drugim lokalizacijama. Tijekom mjeseci datoteke se razilaze: ključevi nedostaju, zastarjeli su ili se ne podudaraju među lokalizacijama.

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
}
Ključevi koji nedostaju gori su od prijevoda koji nedostaju. Za prijevod koji nedostaje može se prikazati izvorni jezik. Ključ koji nedostaje uzrokuje pogrešku pri izvođenju, korisniku prikazuje sirovu putanju ključa ili iscrtava prazan tekst. Sinkronizaciju treba nametnuti, a ne prepustiti slučaju.
2

Otkrivanje ključeva koji nedostaju

Ključ koji nedostaje postoji u izvornoj, ali ne i u ciljnoj lokalizaciji. To je najčešći i najštetniji problem sinkronizacije: korisnici umjesto prevedenog teksta vide sirove putanje poput 'settings.notifications.title'. i18n-validate otkriva takve ključeve usporedbom strukture svake lokalizacije s izvornom.

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)
Pokrenite i18n-validate s oznakom --check missing-keys kako biste se usredotočili na probleme sinkronizacije. Uz --severity error ključevi koji nedostaju rušit će CI provjeru, pa ih je potrebno ispraviti prije spajanja.
3

Otkrivanje zastarjelih ključeva

Zastarjeli ključ postoji u datotekama prijevoda, ali kôd ga više ne upotrebljava. Takvi ključevi troše vrijeme prevoditelja, jer prevode tekstove koje nitko ne vidi, povećavaju paket i otežavaju održavanje. Za njihovo otkrivanje treba usporediti datoteke lokalizacije s referencama u kodu.

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

Automatizacija sinkronizacije

Najučinkovitija strategija sinkronizacije spaja tri razine: 1) Pre-commit hookove koji provjeravaju sinkronizaciju pri svakom commitu. 2) Provjere u CI pipelineu koje blokiraju spajanje ako postoje problemi. 3) Periodične potpune preglede koji otkrivaju razilaženja nastala hitnim popravcima i ručnim izmjenama.

.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

Izvješćivanje o pokrivenosti prijevoda

Pokrivenost prijevoda postotak je izvornih ključeva koji imaju prijevod u svakoj ciljnoj lokalizaciji. i18n-validate generira izvješće s postotkom po lokalizaciji i ističe one koje zaostaju. Pragovima pokrivenosti u CI-ju blokirajte spajanja kada pokrivenost padne ispod prihvatljive razine.

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
Postavite različite pragove pokrivenosti za različite lokalizacije. Primarne lokalizacije (de, fr, ja) mogu zahtijevati 100%, dok novododane (th, vi) mogu početi s 80% i postupno podizati prag.

Isprobajte i18n Agent odmah

Povucite datoteku za prijevod ovdje

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

ili kliknite za odabir

Ciljni jezici

Registracija nije potrebnaProcjena odmah

Česta pitanja o sinkronizaciji datoteka prijevoda