Skip to main content

Sinhronizacija datoteka prevoda: uskladite i18n ključeve u svim lokalima

Svaki put kada programer doda ključ u izvorni lokal, ostalih 15 datoteka lokala ispada iz sinhronizacije. Nedostajući ključevi prikazuju korisnicima neobrađene putanje. Zastareli ključevi troše vreme prevodilaca i povećavaju paket. Automatizovana sinhronizacija održava sve usklađenim.

1

Problem sinhronizacije

Datoteke prevoda neprestano se razilaze. Programer dodaje 'settings.notifications.title' u en.json, ali zaboravlja da ga doda u ostalih 15 datoteka lokala. Drugi programer uklanja 'onboarding.welcome' iz koda, ali ga ostavlja u svim datotekama lokala. Treći menja ime 'user.name' u 'user.displayName' na engleskom, ali ne i u drugim lokalima. Tokom meseci datoteke lokala se razilaze: ključevi nedostaju, zastarevaju ili se ne podudaraju među lokalima.

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
}
Nedostajući ključevi su gori od nedostajućih prevoda. Nedostajući prevod može da pređe na izvorni jezik. Nedostajući ključ izaziva grešku tokom izvršavanja, prikazuje korisniku neobrađenu putanju ključa ili prazan tekst. Sinhronizacija mora da se sprovodi, a ne da se prepušta nadi.
2

Otkrivanje nedostajućih ključeva

Nedostajući ključ postoji u izvornom lokalu, ali ne i u ciljnom. To je najčešći i najštetniji problem sinhronizacije — korisnici vide neobrađene putanje ključeva poput 'settings.notifications.title' umesto prevedenog teksta. i18n-validate otkriva nedostajuće ključeve poređenjem strukture ključeva svakog lokala sa izvornim.

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 sa oznakom --check missing-keys da se usredsredite samo na probleme sinhronizacije. Koristite --severity error da nedostajući ključevi obore CI sistem i obezbede ispravku pre spajanja.
3

Otkrivanje zastarelih ključeva

Zastareli ključ postoji u datotekama prevoda, ali se više ne navodi u kodu. Zastareli ključevi troše vreme prevodilaca (prevodioci prevode tekstove koje niko ne vidi), povećavaju veličinu paketa i stvaraju zabunu pri održavanju. Za otkrivanje zastarelih ključeva potrebno je povezati datoteke lokala sa 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 sinhronizacije

Najdelotvornija strategija sinhronizacije kombinuje tri sloja: 1) pre-commit hook funkcije koje proveravaju sinhronizaciju pri svakom commit koraku; 2) CI pipeline provere koje blokiraju spajanja sa problemima sinhronizacije; 3) periodične potpune provere koje otkrivaju odstupanja nagomilana hitnim ispravkama i ručnim izmenama.

.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

Izveštavanje o pokrivenosti prevoda

Pokrivenost prevoda je procenat izvornih ključeva koji imaju prevode u svakom ciljnom lokalu. i18n-validate generiše izveštaj o pokrivenosti sa procentima za svaki lokal i ističe lokale koji zaostaju. Koristite pragove pokrivenosti u CI sistemu da blokirate spajanja kada pokrivenost padne ispod prihvatljivog nivoa.

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 lokale. Glavni lokali (de, fr, ja) mogu da zahtevaju pokrivenost od 100%, dok novododati lokali (th, vi) mogu da počnu sa 80% i postepeno se povećavaju.

Isprobajte i18n Agent sada

Pustite datoteku za prevođenje ovde

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

ili kliknite za izbor

Ciljni jezici

Registracija nije potrebnaTrenutna procena

Česta pitanja o sinhronizaciji datoteka prevoda