Skip to main content

Синхронизиране на файлове с преводи: поддържайте ключовете за i18n синхронизирани във всички локали

Всеки път, когато разработчик добави ключ към изходната езикова настройка, останалите 15 файла с езикови настройки вече не са синхронизирани. При липсващи ключове потребителите виждат необработени пътища. Остарелите ключове губят времето на преводачите и увеличават размера на пакета. Автоматичното синхронизиране поддържа всичко съгласувано.

1

Проблемът със синхронизацията

Файловете с преводи постоянно се разминават. Разработчик добавя 'settings.notifications.title' към en.json, но забравя да го добави към останалите 15 файла с локали. Друг разработчик премахва 'onboarding.welcome' от кода, но го оставя във всички файлове с локали. Трети преименува 'user.name' на 'user.displayName' в английския файл, но не и в останалите локали. С течение на месеците файловете Ви с локали се разминават: ключовете липсват, остаряват или не съответстват между отделните локали.

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
}
Липсващите ключове са по-сериозен проблем от липсващите преводи. При липсващ превод може да се използва текстът на изходния език. Липсващият ключ причинява грешка по време на изпълнение, показва на потребителя необработен път до ключа или визуализира празен низ. Синхронизацията трябва да се налага, а не да се оставя на случайността.
2

Откриване на липсващи ключове

Липсващ е ключ, който съществува в изходната езикова настройка, но не и в целевата. Това е най-честият и най-вредният проблем със синхронизацията — потребителите виждат необработени пътища до ключове като 'settings.notifications.title' вместо преведен текст. i18n-validate открива липсващите ключове, като сравнява структурата на ключовете във всяка езикова настройка с изходната.

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)
Изпълнете i18n-validate с флага --check missing-keys, за да се съсредоточите конкретно върху проблемите със синхронизацията. Използвайте --severity error, така че липсващите ключове да прекъсват CI и да бъдат отстранявани преди сливането.
3

Откриване на остарели ключове

Остарял е ключ, който съществува във файловете с преводи, но вече не се използва в кода. Остарелите ключове губят времето на преводачите (те превеждат низове, които никой не вижда), увеличават размера на пакета и създават неяснота при поддръжката. Откриването им изисква съпоставяне на файловете с локали с препратките в кода.

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

Автоматизиране на синхронизацията

Най-ефективната стратегия за синхронизация съчетава три нива: 1) Hook-ове преди commit, които валидират синхронизацията при всеки commit. 2) Проверки в CI пайплайна, които блокират сливанията при проблеми със синхронизацията. 3) Периодични пълни проверки, които откриват натрупаните отклонения вследствие на спешни корекции и ръчни промени.

.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

Отчитане на покритието на преводите

Покритието на преводите е процентът от изходните ключове, за които има превод във всяка целева езикова настройка. i18n-validate генерира отчет за покритието с проценти за всяка езикова настройка и откроява тези, които изостават. Използвайте прагове за покритие в CI, за да блокирате сливанията, когато покритието спадне под приемливо ниво.

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
Задайте различни прагове за покритие за отделните локали. За основните Ви локали (de, fr, ja) може да се изисква 100% покритие, докато новодобавените локали (th, vi) могат да започнат от 80%, а прагът постепенно да се повишава.

Изпробвайте i18n Agent сега

Пуснете тук Вашия файл за превод

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

или натиснете, за да изберете файл

Целеви езици

Не се изисква регистрацияНезабавна оценка

Често задавани въпроси за синхронизирането на файлове с преводи