Skip to main content

翻译文件同步：保持各区域设置的 i18n 键同步

每当开发者向源区域设置添加一个键，其他 15 个区域设置文件就会失去同步。缺失键会向用户显示原始路径，过时键则浪费译者时间并增大软件包。自动同步可让所有内容保持一致。

1

同步问题

翻译文件不断产生偏差。一位开发者向 en.json 添加 'settings.notifications.title'，却忘记添加到其他 15 个区域设置文件。另一位开发者从代码中移除 'onboarding.welcome'，却将它留在所有区域设置文件中。第三位开发者在英语文件中将 'user.name' 重命名为 'user.displayName'，但未更新其他区域设置。几个月后，区域设置文件开始分化：不同文件间出现缺失、过时或不匹配的键。

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
}
缺失键比缺失翻译更糟。缺失翻译可以回退到源语言；缺失键则会导致运行时错误、向用户显示原始键路径或呈现空字符串。同步必须强制执行，不能寄希望于人工自觉。
2

检测缺失键

缺失键是源区域设置中存在、但目标区域设置中不存在的键。这是最常见、破坏性也最大的同步问题：用户会看到 'settings.notifications.title' 等原始键路径，而不是翻译文本。i18n-validate 通过比较每个区域设置与源文件的键结构来检测缺失键。

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)
使用 --check missing-keys 标志运行 i18n-validate，可专门检查同步问题。使用 --severity error 让缺失键导致 CI 失败，确保在合并前修复。
3

检测过时键

过时键存在于翻译文件中，但代码已不再引用。它们会浪费译者时间（翻译无人看到的字符串）、增大软件包，并造成维护混乱。检测过时键需要交叉检查区域设置文件和代码引用。

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

自动同步

最有效的同步策略结合三层保障：1）每次提交时验证同步的预提交钩子；2）阻止存在同步问题的合并的 CI 管线检查；3）发现热修复和手动编辑所累积偏差的定期全面审核。

.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

翻译覆盖率报告

翻译覆盖率是每个目标区域设置中已翻译源键的百分比。i18n-validate 会生成显示各区域设置百分比的覆盖率报告，突出显示进度落后的区域设置。在 CI 中使用覆盖率阈值，当覆盖率降至可接受水平以下时阻止合并。

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
为不同区域设置设定不同覆盖率阈值。主要区域设置（de、fr、ja）可能要求 100% 覆盖，新添加的区域设置（th、vi）则可从 80% 开始，并随时间逐步提高。

立即试用 i18n Agent

将翻译文件拖放到此处

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

或点击选择文件

目标语言

无需注册即时估价

翻译文件同步常见问题