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 翻译验证常见问题