Samstilling þýðingarskráa: Haltu i18n-lyklum samstilltum milli staðfærslna
Í hvert sinn sem forritari bætir lykli við frumstaðfærsluna hætta 15 aðrar staðfærsluskrár að vera samstilltar. Lyklar sem vantar birta notendum óunnar slóðir. Úreltir lyklar sóa tíma þýðenda og stækka hugbúnaðarpakkann. Sjálfvirk samstilling heldur öllu samræmdu.
Samstillingarvandinn
Þýðingarskrár færast sífellt í sundur. Forritari bætir 'settings.notifications.title' við en.json en gleymir að bæta lyklinum við hinar 15 staðfærsluskrárnar. Annar forritari fjarlægir 'onboarding.welcome' úr kóðanum en skilur lykilinn eftir í öllum staðfærsluskrám. Sá þriðji endurnefnir 'user.name' sem 'user.displayName' í ensku en ekki í öðrum staðfærslum. Með tímanum fara staðfærsluskrárnar þínar hver í sína átt: lykla vantar, þeir eru úreltir eða samsvara ekki milli staðfærslna.
// 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
}Greining lykla sem vantar
Lykill sem vantar er til í frumstaðfærslunni en ekki í markstaðfærslu. Þetta er algengasta og skaðlegasta samstillingarvandamálið — notendur sjá óunnar lykilslóðir á borð við 'settings.notifications.title' í stað þýdds texta. i18n-validate finnur lykla sem vantar með því að bera lyklauppbyggingu hverrar staðfærslu saman við frumstaðfærsluna.
# 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)Greining úreltra lykla
Úreltur lykill er í þýðingarskrám en hvergi lengur notaður í kóðanum. Úreltir lyklar sóa tíma þýðenda, sem þýða strengi sem enginn sér, stækka hugbúnaðarpakka og valda ruglingi í viðhaldi. Til að finna þá þarf að bera staðfærsluskrár saman við tilvísanir í kóðanum.
# 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-keysSjálfvirk samstilling
Árangursríkasta samstillingaraðferðin sameinar þrjú lög: 1) Pre-commit-krækjur sem sannprófa samstillingu við hvert commit. 2) Prófanir í CI-vinnslurás sem hindra sameiningar með samstillingarvandamál. 3) Reglulegar heildarúttektir sem finna frávik sem hafa safnast upp vegna flýtileiðréttinga og handvirkra breytinga.
# .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.'
})Skýrslur um þýðingaþekju
Þýðingaþekja er hlutfall frumlykla sem hafa þýðingu í hverri markstaðfærslu. i18n-validate býr til þekjuskýrslu með hlutfalli fyrir hverja staðfærslu og dregur fram þær sem dragast aftur úr. Notaðu þekjumörk í CI til að hindra sameiningar þegar þekjan fer niður fyrir ásættanlegt stig.
// 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 workflowsPrófaðu i18n Agent núna
Slepptu þýðingarskránni þinni hér
JSON, YAML, PO, XML, CSV, Markdown, Properties
eða smelltu til að fletta
Markmál