Skip to main content

Sinhronizacija prevajalskih datotek: uskladite ključe i18n med jezikovnimi različicami

Vsakič ko razvijalec doda ključ v izvorno jezikovno različico, 15 drugih jezikovnih datotek ni več usklajenih. Manjkajoči ključi uporabnikom pokažejo neobdelane poti. Zastareli ključi tratijo čas prevajalcev in povečujejo velikost paketa. Samodejna sinhronizacija ohranja vse usklajeno.

1

Težava s sinhronizacijo

Prevajalske datoteke se nenehno oddaljujejo druga od druge. Razvijalec v en.json doda 'settings.notifications.title', vendar ga pozabi dodati v 15 drugih jezikovnih datotek. Drug razvijalec iz kode odstrani 'onboarding.welcome', vendar ga pusti v vseh jezikovnih datotekah. Tretji razvijalec v angleščini preimenuje 'user.name' v 'user.displayName', v drugih jezikovnih različicah pa ne. V nekaj mesecih se Vaše jezikovne datoteke razhajajo: ključi manjkajo, so zastareli ali pa se med jezikovnimi različicami ne ujemajo.

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
}
Manjkajoči ključi so hujši od manjkajočih prevodov. Pri manjkajočem prevodu je mogoč povratek na izvorni jezik. Manjkajoči ključ povzroči napako med izvajanjem, uporabniku pokaže neobdelano pot ključa ali izriše prazen niz. Sinhronizacijo morate zagotavljati, ne pa vanjo zgolj upati.
2

Odkrivanje manjkajočih ključev

Manjkajoči ključ je ključ, ki obstaja v izvorni, ne pa tudi v ciljni jezikovni različici. To je najpogostejša in najbolj škodljiva težava s sinhronizacijo: uporabniki namesto prevedenega besedila vidijo neobdelane poti ključev, kot je 'settings.notifications.title'. i18n-validate manjkajoče ključe odkrije tako, da strukturo ključev vsake jezikovne različice primerja z izvorno.

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)
Če se želite osredotočiti samo na težave s sinhronizacijo, i18n-validate zaženite z zastavico --check missing-keys. Z --severity error zagotovite, da CI zaradi manjkajočih ključev spodleti in da so ti odpravljeni pred združitvijo.
3

Odkrivanje zastarelih ključev

Zastarel ključ obstaja v prevajalskih datotekah, vendar se koda nanj ne sklicuje več. Zastareli ključi tratijo čas prevajalcev (ti prevajajo besedila, ki jih nihče ne vidi), povečujejo velikost paketa in povzročajo zmedo pri vzdrževanju. Za njihovo odkrivanje je treba jezikovne datoteke navzkrižno primerjati s sklici v kodi.

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

Avtomatizacija sinhronizacije

Najučinkovitejša strategija sinhronizacije združuje tri ravni: 1) hooke pre-commit, ki preverjajo sinhronizacijo pri vsakem commitu; 2) preverjanja v pipelineu CI, ki preprečijo združitve s težavami pri sinhronizaciji; 3) redne celovite preglede, ki odkrijejo razhajanja zaradi nujnih popravkov in ročnih sprememb.

.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

Poročanje o pokritosti prevodov

Pokritost prevodov je odstotek izvornih ključev, ki imajo prevode v posamezni ciljni jezikovni različici. i18n-validate ustvari poročilo o pokritosti z odstotkom za vsako različico in poudari različice, ki zaostajajo. S pragovi pokritosti v CI preprečite združitve, kadar pokritost pade pod sprejemljivo raven.

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
Za različne jezikovne različice nastavite različne pragove pokritosti. Za svoje glavne različice (de, fr, ja) lahko zahtevate 100-odstotno pokritost, nove različice (th, vi) pa lahko začnejo pri 80 % in prag sčasoma zvišujejo.

Preizkusite i18n Agent zdaj

Spustite prevajalsko datoteko sem

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

ali kliknite za izbiro

Ciljni jeziki

Registracija ni potrebnaTakojšnja ocena

Pogosta vprašanja o sinhronizaciji prevajalskih datotek