Skip to main content

Sinkronisasi File Terjemahan: Jaga Kunci i18n Tetap Sinkron di Semua Locale

Setiap kali developer menambahkan kunci ke locale sumber, 15 file locale lainnya menjadi tidak sinkron. Kunci yang tidak tersedia menampilkan jalur mentah kepada pengguna. Kunci basi membuang waktu penerjemah dan ukuran bundle. Sinkronisasi otomatis menjaga semuanya tetap selaras.

1

Masalah Sinkronisasi

File terjemahan terus menyimpang. Developer menambahkan 'settings.notifications.title' ke en.json, tetapi lupa menambahkannya ke 15 file locale lainnya. Developer lain menghapus 'onboarding.welcome' dari kode, tetapi membiarkannya dalam semua file locale. Developer ketiga mengganti nama 'user.name' menjadi 'user.displayName' dalam bahasa Inggris, tetapi tidak dalam locale lain. Setelah berbulan-bulan, file locale Anda menyimpang: ada kunci yang tidak tersedia, basi, atau tidak cocok antar-locale.

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
}
Kunci yang tidak tersedia lebih buruk daripada terjemahan yang tidak tersedia. Terjemahan yang tidak tersedia dapat melakukan fallback ke bahasa sumber. Kunci yang tidak tersedia menyebabkan kesalahan runtime, menampilkan jalur kunci mentah kepada pengguna, atau merender string kosong. Sinkronisasi harus ditegakkan, bukan sekadar diharapkan.
2

Mendeteksi Kunci yang Tidak Tersedia

Kunci yang tidak tersedia adalah kunci yang ada dalam locale sumber, tetapi tidak dalam locale target. Ini adalah masalah sinkronisasi paling umum dan paling merusak — pengguna melihat jalur kunci mentah seperti 'settings.notifications.title' alih-alih teks terjemahan. i18n-validate mendeteksi kunci yang tidak tersedia dengan membandingkan struktur kunci setiap locale 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 flag --check missing-keys untuk berfokus secara khusus pada masalah sinkronisasi. Gunakan --severity error agar kunci yang tidak tersedia menggagalkan CI dan memastikan kunci diperbaiki sebelum penggabungan.
3

Mendeteksi Kunci Basi

Kunci basi adalah kunci yang ada dalam file terjemahan, tetapi tidak lagi direferensikan dalam kode. Kunci basi membuang waktu penerjemah (penerjemah menerjemahkan string yang tidak dilihat siapa pun), meningkatkan ukuran bundle, dan membingungkan pemeliharaan. Mendeteksi kunci basi memerlukan pemeriksaan silang antara file locale dan referensi kode.

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

Mengotomatiskan Sinkronisasi

Strategi sinkronisasi paling efektif menggabungkan tiga lapisan: 1) Hook pre-commit yang memvalidasi sinkronisasi pada setiap commit. 2) Pemeriksaan pipeline CI yang memblokir penggabungan bermasalah. 3) Audit penuh berkala yang menemukan penyimpangan terakumulasi dari hotfix dan pengeditan 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 Cakupan Terjemahan

Cakupan terjemahan adalah persentase kunci sumber yang memiliki terjemahan dalam setiap locale target. i18n-validate menghasilkan laporan cakupan yang menunjukkan persentase per locale dan menyoroti locale yang tertinggal. Gunakan ambang cakupan di CI untuk memblokir penggabungan ketika cakupan turun di bawah tingkat yang dapat 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
Atur ambang cakupan berbeda untuk locale berbeda. Locale utama Anda (de, fr, ja) mungkin memerlukan cakupan 100%, sedangkan locale yang baru ditambahkan (th, vi) dapat dimulai dari 80% dan dinaikkan secara bertahap.

Coba i18n Agent Sekarang

Lepaskan file terjemahan Anda di sini

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

atau klik untuk menjelajahi

Bahasa target

Tidak perlu mendaftarEstimasi instan

Tanya Jawab Sinkronisasi File Terjemahan