
CI 翻譯驗證:在管線中自動執行 i18n 檢查
程式碼審核看不到翻譯缺陷。缺失鍵、損壞的預留位置、格式錯誤的複數都不會在差異中顯現。CI 級驗證可在它們進入生產環境前發現問題。
翻譯缺陷為何會逃過程式碼審核
開發人員向 en.json 新增 10 個新鍵並更新功能程式碼。PR 審核者檢查程式碼、驗證英語字串並批准,但無人比較其他 14 個語系檔案。三個缺陷進入生產環境:de.json 缺少 2 個鍵(德國使用者看到原始鍵路徑);fr.json 的 {count} 預留位置損壞(法國使用者看到字面 {count});ja.json 的 ICU 複數格式錯誤(日本使用者遇到崩潰)。只需 30 秒的 CI 檢查即可避免這些問題。
安裝 i18n-validate
將 i18n-validate 作為開發相依性新增到專案。它開箱即用地支援 JSON、YAML、PO、XLIFF 和 ARB 格式,基本用法無需設定。
npm install --save-dev @anthropic/i18n-validateGitHub Actions 整合
在拉取請求工作流中新增 i18n-validate 步驟。發現錯誤時,該工具以程式碼 1 退出,使 PR 檢查失敗。結合 JUnit XML 輸出和測試報告操作,可直接在 PR 差異上顯示內嵌註解。
# .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.xmlGitLab CI 整合
向 .gitlab-ci.yml 管線新增翻譯驗證作業。GitLab 原生支援 JUnit XML 工件,上傳驗證報告後,錯誤會顯示在合併請求的 Test 選項卡中。
# .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/**/*預提交鈎子
為更快獲得反饋,將驗證作為預提交鈎子執行。這樣可在問題進入 CI 前發現它們,節省管線時間並縮短反饋循環。使用 Husky(JS)或 pre-commit(Python)管理鈎子。
# .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設定和嚴重性級別
使用 .i18n-validate.toml 設定檔案自訂驗證行為。為每條規則設定檢查嚴重性(error、warning、off),定義預期語言、排除開發中的語系並設定輸出格式。在 CI 中,僅錯誤會使管線失敗;警告會顯示在報告中,但不會阻止。
// 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
或點擊選擇檔案
目標語言