在 GitHub Actions 中检查翻译

工作流

将其另存为 .github/workflows/i18n-check.yml。将 source 更改为您的基础语言文件，将 languages 更改为您发布的区域设置。

name: i18n check
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kaeris-io/kaeris-action@v1
        with:
          mode: check
          source: locales/en.json
          languages: de,fr

不用 Python：npx

npm 包 kaeris 在 Node 18 及以上版本运行同样的检查；npx 会自动下载，无需安装步骤。包里只有 check：翻译需要 Python 包。

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx kaeris check --source locales/en.json --langs de,fr

不带 Action 的相同功能

使用 Python 和 pip 的纯粹步骤。日志会逐行显示每个发现项，而不是 Action 打印的表格。

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install kaeris
      - run: kaeris check --source locales/en.json --langs de,fr --ci

在合并请求的确切行上发现问题（可选）

Action 还可以生成 SARIF 报告；上传该报告会将每个发现项转换为 diff 中的注释。代码扫描上传在公共仓库上是免费的；私有仓库需要 GitHub Advanced Security。

name: i18n check
on: pull_request
permissions:
  contents: read
  security-events: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kaeris-io/kaeris-action@v1
        with:
          mode: check
          source: locales/en.json
          languages: de,fr
          sarif-file: kaeris.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: kaeris.sarif

作业打印的内容

Action 为每种语言打印一个摘要表，并在出现问题时以错误行结尾。左侧：正常的文件。右侧：de.json 文件，其中包含 {nam} 而不是 {name}，并且 checkout 键丢失。

## KAERIS i18n — CI check

Placeholder-loss: **0** (should be 0).

| Language | Status | Missing | Placeholder issues | Translated |
|---|---|---|---|---|
| de | ✓ complete | 0 | 0 | – |
| fr | ✓ complete | 0 | 0 | – |

_Generated from `kaeris check --json` — no fabricated numbers._
step exit=0
--- GITHUB_OUTPUT (without summary body):
missing=0
placeholder-issues=0
changed=false
check-exit-code=0
translate-exit-code=0

## KAERIS i18n — CI check

Placeholder-loss: **1** (should be 0).
Missing keys remaining: **1**.

| Language | Status | Missing | Placeholder issues | Translated |
|---|---|---|---|---|
| de | ⚠ 1 missing, 1 placeholder issue | 1 | 1 | – |
| fr | ✓ complete | 0 | 0 | – |

_Generated from `kaeris check --json` — no fabricated numbers._
::error::kaeris check found incomplete/broken translations — see the job summary for the language matrix
step exit=1
--- GITHUB_OUTPUT (without summary body):
missing=1
placeholder-issues=1
changed=false
check-exit-code=1
translate-exit-code=0

npx 步骤的输出

同一个项目用 npx 检查：来自 npm 的 kaeris 0.2.37，空的 npm 缓存，CI=true，与全新 runner 相同。第一行是 npm 在安装这个包。

$ npx kaeris check --source locales/en.json --langs de,fr
npm warn exec The following package was not found and will be installed: [email protected]
✓ de: complete & placeholder-safe
✓ fr: complete & placeholder-safe
✓ all locales complete & placeholder-safe
exit code: 0

$ npx kaeris check --source locales/en.json --langs de,fr
npm warn exec The following package was not found and will be installed: [email protected]
✗ de: 1 missing key(s): checkout
✗ de: 1 placeholder mismatch(es):
    greeting: missing ['{name}'], added ['{nam}']
✗ de: 2 translation fault(s):
    greeting: lost placeholder {name}
    greeting: invented placeholder {nam} (not in source)
✓ fr: complete & placeholder-safe
✗ 1 missing key, 1 placeholder mismatch, 2 translation faults
exit code: 1

1. 保存工作流

   创建 .github/workflows/i18n-check.yml 文件，其中包含上述工作流，并配置你自己的 source 和 languages。

2. 打开一个合并请求

   推送一个更改了区域设置文件的分支。该作业会在每个合并请求上运行，并在丢失占位符或缺少键时显示红色。

3. 将检查设为必需

   在仓库设置中，将该作业添加为分支保护中的必需状态检查。红色的作业将阻止合并。

• 已运行的命令

  kaeris-io/kaeris-action 的步骤脚本，版本为 v1，于 27 October 2026 从 GitHub 复制并在测试项目上使用 bash 运行，通过 PyPI 安装了 CLI（kaeris 0.2.35）。干净的文件：退出代码 0。损坏的 de.json：退出代码 1，并显示了上面的错误行。

• npx

  npm 包 kaeris 0.2.37 的 npx kaeris check 于 2026年10月28日 在同一个测试项目上运行。npm 缓存为空，CI=true，不带 --yes。正常文件：退出码 0。损坏的 de.json：退出码 1。

• SARIF

  在损坏的项目上运行了 --sarif 标志，并输出了包含 4 个结果的报告；在干净的文件上，它输出了包含 0 个结果的报告。尚未尝试上传到 GitHub。

• 未运行的部分

  工作流文件本身未在 GitHub Runner 上运行，actions/checkout、actions/setup-python、actions/setup-node 和 upload-sarif 也未运行。GitHub 未检查上述工作流的语法。

• Action 安装的 CLI 版本

  Action 运行 pip install "kaeris>=0.2.12"，因此作业会获取当时的最新发布版本。如果你需要固定版本，请使用纯粹步骤变体并固定版本：pip install kaeris==0.2.35。

• 对过时的键也失败

  在 Action 上设置 strict: true（或在纯粹变体中使用 --strict）。

• 翻译在另一个文件夹中

  在 Action 上设置 out: path/to/translations；默认情况下，它使用源文件的文件夹。

• 保留品牌名称不变

  --glossary 'KAERIS,GitHub' 会使丢失其中一个术语的目标失败。相同的列表可以放在 kaeris.json 的 keep 下。

• 不同的文件布局

  --out 是包含翻译的文件夹，--pattern '{lang}/common.json' 是它们的文件名。默认：kaeris translate 写入的布局。

其他配置示例：GitLab CI · pre-commit · Make 和 npm 脚本

CLI 参考 · 检查参考 · GitHub Action 参考 · 浏览器中的免费检查 · 浏览器中的翻译