Skip to main content

Penyegerakan Fail Terjemahan: Pastikan Kekunci i18n Disegerakkan Merentas Semua Lokal

Setiap kali pembangun menambahkan kekunci pada lokal sumber, 15 fail lokal lain menjadi tidak segerak. Kekunci yang tiada memaparkan laluan mentah kepada pengguna. Kekunci lapuk membazirkan masa penterjemah dan saiz bundle. Penyegerakan automatik memastikan semuanya kekal selaras.

1

Masalah Penyegerakan

Fail terjemahan sentiasa menyimpang. Pembangun menambahkan 'settings.notifications.title' pada en.json, tetapi terlupa menambahkannya pada 15 fail lokal lain. Pembangun lain membuang 'onboarding.welcome' daripada kod, tetapi membiarkannya dalam semua fail lokal. Pembangun ketiga menamakan semula 'user.name' menjadi 'user.displayName' dalam bahasa Inggeris, tetapi tidak dalam lokal lain. Selepas berbulan-bulan, fail lokal anda menyimpang: terdapat kekunci yang tiada, lapuk, atau tidak sepadan antara lokal.

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
}
Kekunci yang tiada lebih buruk daripada terjemahan yang tiada. Terjemahan yang tiada boleh bersandar kepada bahasa sumber. Kekunci yang tiada menyebabkan ralat masa jalan, memaparkan laluan kekunci mentah kepada pengguna, atau memaparkan rentetan kosong. Penyegerakan mesti dikuatkuasakan, bukan sekadar diharapkan.
2

Mengesan Kekunci yang Tiada

Kekunci yang tiada ialah kekunci yang wujud dalam lokal sumber, tetapi tiada dalam lokal sasaran. Ini ialah masalah penyegerakan paling lazim dan paling merosakkan — pengguna melihat laluan kekunci mentah seperti 'settings.notifications.title' dan bukannya teks terjemahan. i18n-validate mengesan kekunci yang tiada dengan membandingkan struktur kekunci setiap lokal terhadap sumber.

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)
Jalankan i18n-validate dengan bendera --check missing-keys untuk berfokus secara khusus pada masalah penyegerakan. Gunakan --severity error supaya kekunci yang tiada menggagalkan CI dan memastikan kekunci dibaiki sebelum penggabungan.
3

Mengesan Kekunci Lapuk

Kekunci lapuk ialah kekunci yang wujud dalam fail terjemahan, tetapi tidak lagi dirujuk dalam kod. Kekunci lapuk membazirkan masa penterjemah (penterjemah menterjemahkan rentetan yang tidak dilihat oleh sesiapa), meningkatkan saiz bundle, dan mengelirukan penyelenggaraan. Mengesan kekunci lapuk memerlukan semakan silang antara fail lokal dan rujukan kod.

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

Mengautomatikkan Penyegerakan

Strategi penyegerakan paling berkesan menggabungkan tiga lapisan: 1) Cangkuk pre-commit yang mengesahkan penyegerakan pada setiap komit. 2) Pemeriksaan saluran CI yang menyekat penggabungan bermasalah. 3) Audit penuh berkala yang mengesan penyimpangan terkumpul daripada hotfix dan penyuntingan manual.

.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

Pelaporan Liputan Terjemahan

Liputan terjemahan ialah peratusan kekunci sumber yang mempunyai terjemahan dalam setiap lokal sasaran. i18n-validate menjana laporan liputan yang menunjukkan peratusan bagi setiap lokal dan menyoroti lokal yang ketinggalan. Gunakan ambang liputan dalam CI untuk menyekat penggabungan apabila liputan turun di bawah tahap yang boleh diterima.

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
Tetapkan ambang liputan berbeza untuk lokal berbeza. Lokal utama anda (de, fr, ja) mungkin memerlukan liputan 100%, manakala lokal yang baru ditambahkan (th, vi) boleh bermula pada 80% dan ditingkatkan secara berperingkat.

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

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

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Soalan Lazim Penyegerakan Fail Terjemahan