Skip to main content

CI 翻譯驗證：在管線中自動執行 i18n 檢查

程式碼審核看不到翻譯缺陷。缺失鍵、損壞的預留位置、格式錯誤的複數都不會在差異中顯現。CI 級驗證可在它們進入生產環境前發現問題。

1

翻譯缺陷為何會逃過程式碼審核

開發人員向 en.json 新增 10 個新鍵並更新功能程式碼。PR 審核者檢查程式碼、驗證英語字串並批准，但無人比較其他 14 個語系檔案。三個缺陷進入生產環境：de.json 缺少 2 個鍵（德國使用者看到原始鍵路徑）；fr.json 的 {count} 預留位置損壞（法國使用者看到字面 {count}）；ja.json 的 ICU 複數格式錯誤（日本使用者遇到崩潰）。只需 30 秒的 CI 檢查即可避免這些問題。

翻譯缺陷具有獨特性質：開發人員和審核者都看不到，只有使用特定語系的使用者才能發現。CI 驗證是在生產環境前可靠發現它們的唯一方式。
2

安裝 i18n-validate

將 i18n-validate 作為開發相依性新增到專案。它開箱即用地支援 JSON、YAML、PO、XLIFF 和 ARB 格式，基本用法無需設定。

Terminal
npm install --save-dev @anthropic/i18n-validate
3

GitHub Actions 整合

在拉取請求工作流中新增 i18n-validate 步驟。發現錯誤時，該工具以程式碼 1 退出，使 PR 檢查失敗。結合 JUnit XML 輸出和測試報告操作，可直接在 PR 差異上顯示內嵌註解。

.github/workflows/i18n-validate.yml
# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - 'src/locales/**'
      - 'public/locales/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Validate translation files
        run: npx i18n-validate \
          --source src/locales/en.json \
          --targets 'src/locales/*.json' \
          --check-missing \
          --check-unused \
          --check-placeholders \
          --check-plurals \
          --min-coverage 95 \
          --junit-output reports/i18n.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: i18n-validation-report
          path: reports/i18n.xml
在工作流中固定 i18n-validate 版本，避免新驗證規則導致意外中斷。僅在開發環境使用 @latest。
4

GitLab CI 整合

向 .gitlab-ci.yml 管線新增翻譯驗證作業。GitLab 原生支援 JUnit XML 工件，上傳驗證報告後，錯誤會顯示在合併請求的 Test 選項卡中。

.gitlab-ci.yml
# .gitlab-ci.yml
i18n-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx i18n-validate \
        --source src/locales/en.json \
        --targets 'src/locales/*.json' \
        --check-missing \
        --check-unused \
        --check-placeholders \
        --min-coverage 95 \
        --junit-output reports/i18n.xml
  artifacts:
    reports:
      junit: reports/i18n.xml
  only:
    changes:
      - src/locales/**/*
5

預提交鈎子

為更快獲得反饋，將驗證作為預提交鈎子執行。這樣可在問題進入 CI 前發現它們，節省管線時間並縮短反饋循環。使用 Husky（JS）或 pre-commit（Python）管理鈎子。

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Only validate if translation files changed
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(locales|i18n|translations)/')

if [ -n "$CHANGED_FILES" ]; then
  echo "Translation files changed, validating..."
  npx i18n-validate \
    --source src/locales/en.json \
    --targets 'src/locales/*.json' \
    --check-missing \
    --check-placeholders
fi
預提交鈎子會在每次提交時執行，因此應保持快速。使用 --locales 標誌只驗證當前提交中更改的語系，而不是所有語系。對於大多數專案，這可將鈎子執行時間保持在 2 秒以內。
6

設定和嚴重性級別

使用 .i18n-validate.toml 設定檔案自訂驗證行為。為每條規則設定檢查嚴重性（error、warning、off），定義預期語言、排除開發中的語系並設定輸出格式。在 CI 中，僅錯誤會使管線失敗；警告會顯示在報告中，但不會阻止。

i18n-validate.config.json
// i18n-validate.config.json
{
  "source": "src/locales/en.json",
  "targets": "src/locales/*.json",
  "checks": {
    "missing": true,         // Keys in source missing from target
    "unused": true,          // Keys in target not in source
    "placeholders": true,    // Mismatched {variables}
    "plurals": true,         // Missing CLDR plural forms
    "icu": true,             // ICU syntax validation
    "emptyValues": true,     // Empty string values
    "duplicateValues": false // Same value as source (untranslated)
  },
  "minCoverage": 95,
  "exclude": [
    "src/locales/pseudo.json"
  ],
  "junitOutput": "reports/i18n.xml",
  "format": "json"          // json | yaml | po | xliff
}

立即試用 i18n Agent

將翻譯檔案拖放到此處

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

或點擊選擇檔案

目標語言

無需註冊即時估價

CI 翻譯驗證常見問題