Синхронізація файлів перекладу: узгоджені ключі i18n у всіх локалях
Щоразу, коли розробник додає ключ до вихідної локалі, 15 інших файлів локалей втрачають синхронізацію. Через відсутні ключі користувачі бачать необроблені шляхи. Застарілі ключі марнують час перекладачів і збільшують розмір пакета. Автоматизована синхронізація підтримує узгодженість усіх файлів.
Проблема синхронізації
Файли перекладу постійно розходяться. Розробник додає 'settings.notifications.title' до en.json, але забуває додати його до інших 15 файлів локалей. Інший розробник видаляє 'onboarding.welcome' з коду, але залишає його в усіх файлах локалей. Ще один перейменовує 'user.name' на 'user.displayName' в англійській, але не в інших локалях. За кілька місяців файли локалей стають неузгодженими: у них бракує ключів, залишаються застарілі ключі або ключі не збігаються між локалями.
// 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
}Виявлення відсутніх ключів
Відсутній ключ — це ключ, який є у вихідній локалі, але відсутній у цільовій. Це найпоширеніша й найшкідливіша проблема синхронізації: користувачі бачать необроблені шляхи ключів на зразок 'settings.notifications.title' замість перекладеного тексту. i18n-validate виявляє відсутні ключі, порівнюючи структуру ключів кожної локалі з вихідною.
# 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)Виявлення застарілих ключів
Застарілий ключ — це ключ, який є у файлах перекладу, але більше не використовується в коді. Застарілі ключі марнують час перекладачів, адже ті перекладають рядки, яких ніхто не бачить, збільшують розмір пакета та ускладнюють супровід. Для виявлення застарілих ключів потрібно зіставити файли локалей із посиланнями на них у коді.
# 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Автоматизація синхронізації
Найефективніша стратегія синхронізації поєднує три рівні: 1) Хуки pre-commit, які перевіряють синхронізацію під час кожного commit. 2) Перевірки в CI-конвеєрі, які блокують об’єднання змін із проблемами синхронізації. 3) Періодичні повні аудити, які виявляють розбіжності, накопичені через термінові виправлення та ручне редагування.
# .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
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.'
})Звіти про охоплення перекладу
Охоплення перекладу — це частка вихідних ключів, які мають переклади в кожній цільовій локалі. i18n-validate створює звіт про охоплення з відсотками для кожної локалі та виділяє локалі, які відстають. Використовуйте порогові значення охоплення в CI, щоб блокувати об’єднання змін, коли показник падає нижче прийнятного рівня.
// 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Спробуйте i18n Agent зараз
Перетягніть сюди файл для перекладу
JSON, YAML, PO, XML, CSV, Markdown, Properties
або натисніть, щоб вибрати
Цільові мови