
CI 翻訳検証:パイプラインで i18n チェックを自動化
翻訳の不具合はコードレビューでは見えません。欠落キー、壊れたプレースホルダー、不正な複数形は、いずれも差分には現れません。CI レベルの検証で、本番環境へ到達する前に検出できます。
翻訳の不具合がコードレビューをすり抜ける理由
開発者が en.json に新しいキーを 10 個追加し、機能コードを更新したとします。PR のレビュアーはコードと英語の文字列を確認して承認しますが、残り 14 個のロケールファイルは誰も比較しません。その結果、3 件の不具合が本番環境へ入ります。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/**/*pre-commit フック
より早くフィードバックするには、pre-commit フックとして検証を実行します。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 では error だけがパイプラインを失敗させ、warning はレポートに表示されますが処理を停止しません。
// 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
またはクリックしてファイルを選択
翻訳先言語