Skip to main content

Synchronizácia prekladových súborov: udržujte kľúče i18n zhodné vo všetkých lokalizáciách

Zakaždým, keď vývojár pridá kľúč do zdrojovej lokalizácie, ďalších 15 lokalizačných súborov prestane byť synchronizovaných. Chýbajúce kľúče zobrazujú používateľom nespracované cesty. Zastarané kľúče plytvajú časom prekladateľov a zväčšujú balík. Automatizovaná synchronizácia udržiava všetko v súlade.

1

Problém synchronizácie

Prekladové súbory sa neustále rozchádzajú. Vývojár pridá 'settings.notifications.title' do en.json, no zabudne ho pridať do ďalších 15 lokalizačných súborov. Iný vývojár odstráni 'onboarding.welcome' z kódu, ale ponechá ho vo všetkých lokalizačných súboroch. Tretí premenuje 'user.name' na 'user.displayName' v angličtine, nie však v ostatných lokalizáciách. V priebehu mesiacov sa Vaše lokalizačné súbory rozídu: kľúče chýbajú, sú zastarané alebo sa medzi lokalizáciami nezhodujú.

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
}
Chýbajúce kľúče sú horšie než chýbajúce preklady. Pri chýbajúcom preklade možno použiť zdrojový jazyk. Chýbajúci kľúč spôsobí chybu za behu, zobrazí používateľovi nespracovanú cestu ku kľúču alebo vykreslí prázdny reťazec. Synchronizáciu treba vynucovať, nie v ňu dúfať.
2

Odhaľovanie chýbajúcich kľúčov

Chýbajúci kľúč existuje v zdrojovej lokalizácii, ale nie v cieľovej. Je to najbežnejší a najškodlivejší problém synchronizácie – používatelia namiesto preloženého textu vidia nespracované cesty ku kľúčom, ako je 'settings.notifications.title'. i18n-validate odhaľuje chýbajúce kľúče porovnaním štruktúry kľúčov každej lokalizácie so zdrojom.

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)
Ak sa chcete zamerať výhradne na problémy synchronizácie, spustite i18n-validate s príznakom --check missing-keys. Pomocou --severity error nechajte pri chýbajúcich kľúčoch zlyhať CI, aby sa opravili pred zlúčením.
3

Odhaľovanie zastaraných kľúčov

Zastaraný kľúč existuje v prekladových súboroch, ale kód sa naň už neodvoláva. Zastarané kľúče plytvajú časom prekladateľov (prekladajú reťazce, ktoré nikto nevidí), zväčšujú balík a komplikujú údržbu. Ich odhalenie vyžaduje porovnanie lokalizačných súborov s odkazmi v kóde.

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

Automatizácia synchronizácie

Najúčinnejšia stratégia synchronizácie kombinuje tri vrstvy: 1) hooky pre-commit, ktoré overujú synchronizáciu pri každom commite, 2) kontroly pipeline CI, ktoré blokujú zlúčenia s problémami synchronizácie, 3) pravidelné úplné audity, ktoré odhaľujú rozdiely nahromadené po rýchlych opravách a manuálnych úpravách.

.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

Prehľad pokrytia prekladov

Pokrytie prekladu je percentuálny podiel zdrojových kľúčov s prekladom v každej cieľovej lokalizácii. i18n-validate vygeneruje správu o pokrytí s percentami jednotlivých lokalizácií a zvýrazní tie, ktoré zaostávajú. Pomocou prahov pokrytia v CI blokujte zlúčenia, keď pokrytie klesne pod prijateľnú úroveň.

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
Pre rôzne lokalizácie nastavte rôzne prahy pokrytia. Vaše hlavné lokalizácie (de, fr, ja) môžu vyžadovať 100 % pokrytie, zatiaľ čo novo pridané (th, vi) môžu začínať na 80 % a postupne sa zvyšovať.

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Časté otázky k synchronizácii prekladových súborov