Skip to main content

CI 翻訳検証：パイプラインで i18n チェックを自動化

翻訳の不具合はコードレビューでは見えません。欠落キー、壊れたプレースホルダー、不正な複数形は、いずれも差分には現れません。CI レベルの検証で、本番環境へ到達する前に検出できます。

1

翻訳の不具合がコードレビューをすり抜ける理由

開発者が en.json に新しいキーを 10 個追加し、機能コードを更新したとします。PR のレビュアーはコードと英語の文字列を確認して承認しますが、残り 14 個のロケールファイルは誰も比較しません。その結果、3 件の不具合が本番環境へ入ります。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

pre-commit フック

より早くフィードバックするには、pre-commit フックとして検証を実行します。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
pre-commit フックはコミットごとに実行されるため、高速に保つ必要があります。全ロケールではなく、--locales フラグで現在のコミットで変更したロケールだけを検証してください。多くのプロジェクトで実行時間を 2 秒未満に抑えられます。
6

設定と重大度レベル

.i18n-validate.toml 設定ファイルで検証動作をカスタマイズできます。規則ごとの重大度（error、warning、off）、対象言語、除外する作業中ロケール、出力形式を設定します。CI では error だけがパイプラインを失敗させ、warning はレポートに表示されますが処理を停止しません。

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 翻訳検証のよくある質問