Синхронизација датотека превода: ускладите 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 hook функције које проверавају синхронизацију при сваком commit кораку; 2) CI pipeline провере које блокирају спајања са проблемима синхронизације; 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
или кликните за избор
Циљни језици