Skip to main content

Sincronizarea fișierelor de traducere: mențineți cheile i18n sincronizate între setările regionale

De fiecare dată când un dezvoltator adaugă o cheie în fișierul-sursă, alte 15 fișiere de localizare își pierd sincronizarea. Cheile lipsă afișează utilizatorilor căi neprelucrate. Cheile perimate consumă inutil timpul traducătorilor și măresc dimensiunea pachetului. Sincronizarea automată menține totul aliniat.

1

Problema sincronizării

Fișierele de traducere se diferențiază constant. Un dezvoltator adaugă 'settings.notifications.title' în en.json, dar uită să o adauge în celelalte 15 fișiere de localizare. Alt dezvoltator elimină 'onboarding.welcome' din cod, dar o păstrează în toate fișierele de localizare. Un al treilea dezvoltator redenumește 'user.name' în 'user.displayName' în engleză, dar nu și în celelalte setări regionale. După câteva luni, fișierele de localizare devin neuniforme: cheile lipsesc, sunt perimate sau nu corespund între setările regionale.

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
}
Cheile lipsă sunt mai grave decât traducerile lipsă. În cazul unei traduceri lipsă, se poate reveni la limba-sursă. O cheie lipsă provoacă o eroare în timpul execuției, afișează utilizatorului calea neprelucrată a cheii sau redă un șir gol. Sincronizarea trebuie impusă, nu lăsată la voia întâmplării.
2

Detectarea cheilor lipsă

O cheie lipsă este o cheie care există în setarea regională-sursă, dar nu și într-o setare regională-țintă. Aceasta este cea mai frecventă și cea mai gravă problemă de sincronizare: utilizatorii văd căi neprelucrate ale cheilor, precum 'settings.notifications.title', în locul textului tradus. i18n-validate detectează cheile lipsă comparând structura cheilor fiecărei setări regionale cu cea a sursei.

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)
Executați i18n-validate cu opțiunea --check missing-keys pentru a vă concentra în mod special asupra problemelor de sincronizare. Utilizați --severity error pentru ca prezența cheilor lipsă să determine eșecul CI și să asigure remedierea lor înainte de îmbinare.
3

Detectarea cheilor perimate

O cheie perimată este o cheie care există în fișierele de traducere, dar nu mai este referențiată în cod. Cheile perimate consumă inutil timpul traducătorilor (aceștia traduc șiruri pe care nu le vede nimeni), măresc dimensiunea pachetului și creează confuzie în activitatea de mentenanță. Detectarea cheilor perimate necesită compararea fișierelor de localizare cu referințele din cod.

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

Automatizarea sincronizării

Cea mai eficientă strategie de sincronizare combină trei niveluri: 1) Hook-uri pre-commit care validează sincronizarea la fiecare commit. 2) Verificări ale fluxului CI care blochează îmbinările cu probleme de sincronizare. 3) Audituri complete periodice care identifică abaterile acumulate în urma remedierilor urgente și a modificărilor manuale.

.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

Raportarea acoperirii traducerilor

Acoperirea traducerilor reprezintă procentul de chei-sursă care au traduceri în fiecare setare regională-țintă. i18n-validate generează un raport de acoperire care afișează procentele pentru fiecare setare regională și le evidențiază pe cele rămase în urmă. Utilizați praguri de acoperire în CI pentru a bloca îmbinările atunci când acoperirea scade sub un nivel acceptabil.

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
Stabiliți praguri de acoperire diferite pentru fiecare setare regională. Setările regionale principale (de, fr, ja) pot necesita o acoperire de 100%, în timp ce cele adăugate recent (th, vi) pot începe de la 80%, pragul crescând treptat.

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Întrebări frecvente despre sincronizarea fișierelor de traducere