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が出力するテーブルではなく、検出された問題が1行ずつ表示されます。

    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レポートも書き出すことができます。それをアップロードすると、各検出結果が差分に注釈として表示されます。コードスキャンアップロードは公開リポジトリでは無料ですが、プライベートリポジトリでは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 で {name} の代わりに {nam} が使われ、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。新しいランナーと同じ条件です。最初の行は 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、2026年10月27日にGitHubからコピーされ、テストプロジェクトでbashで実行されました。CLIはPyPIからインストールされました（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 ランナーで実行しておらず、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リファレンス · Checkリファレンス · GitHub Actionリファレンス · ブラウザでの無料チェック · ブラウザでの翻訳