i18n Doctor: ワンコマンドで完全な翻訳ヘルスレポートを取得
Run better-i18n doctorを実行して、コード品質、翻訳カバレッジ、プレースホルダーの正確性、孤立キー、CDN同期という5つの次元からコードベース全体を分析し、実行可能な診断情報付きの0～100の総合健全性スコアを取得します。
$ better-i18n doctor
better-i18n · i18nドクターレポート
████████████████░░░░ 82 / 100 A
PASSED (threshold: 70)
Coverage 95 (3 issues)
Quality 88 (2 issues)
Code 72 (8 issues)
Structure 100 (clean)
Performance 91 (1 issue)解析
単一パスにおける5つの分析レイヤー
Doctorはコードスキャン、カバレッジ分析、品質検証、パフォーマンス監査、CDN同期チェックをすべて同時に実行し、統一スコアを提供します。
コード — ハードコードされた文字列の検出
ASTベースのスキャンは、t()で囲まれていないユーザー向け文字列をすべて検出します。JSXテキスト、属性、三項ロケールロジック、トーストメッセージ、文字列変数を捕捉します。
カバレッジ — 翻訳が不足している箇所
ソースロケールに存在するキーを各ターゲットロケールと比較します。ターゲットロケールに存在しないキーは、その正確な名前空間とパスとともに報告されます。
品質 — プレースホルダーの不一致
補間プレースホルダーが全ロケールで一貫していることを検証します。名前付き{}、二重中括弧{{}}、printf%s、テンプレート${}、位置指定{0}の各形式をサポートします。
パフォーマンス — 孤立キー検出
翻訳ファイルに存在するがコード内で参照されないキーを検出します。孤立したキーはペイロードサイズを増加させ、保守負債を生み出します。
同期 — CDN 比較
コードから抽出されたキーをCDNに公開されているキーと比較します。本番環境に影響が出る前に、リモート側で欠落しているキーや未使用のリモートキーの問題を検出します。
スコアリング
翻訳の健康状態を示す単一スコア
医師は診断結果に基づき0から100までのスコアを算出する。エラーは1件あたり3.0ポイント減点される一方、各ルールの警告寄与度は20ポイントに制限される。これにより、数千件の警告を含む単一ルールによってスコア全体がゼロになる事態を防止する。
デフォルトの合格閾値は70（B評価）です。この閾値を下回るビルドを不合格にするには--ciオプションを使用し、スコア適用前に基準値を設定するには--reportオプションから開始してください。
スコア計算式
score = 100 - (errors × 3.0) - Σ min(rule_warnings × 0.15, 20)成績基準
- A+
- ≥ 90
- A
- ≥ 80
- B
- ≥ 70
- C
- ≥ 50
- F
- < 50
継続的インテグレーション
CI/CD統合 — 悪い翻訳が出荷される前にブロックする
CIパイプラインにdoctorを追加して、プッシュのたびに翻訳の退行を検出しましょう。GitHub Actionsでの自動OIDC認証により、シークレット管理が不要になります。
GitHub Actions と OIDC
GitHub Actions OIDCを使用してAPIキーなしで自動的に認証します。id-token: write権限を追加し、`doctor --ci --report`を実行するだけです。
閾値ゲート
合格閾値を設定（デフォルト: 70）し、スコアがこれを下回った場合にビルドを失敗させる。--report で追跡を開始し、--ci で強制する。
機械可読JSON
構造化された出力には --format json オプションを使用してください。これにより、jq へのパイプ処理、カスタムダッシュボード、またはデプロイメントパイプライン内の下流自動化への連携が可能になります。
ダッシュボードレポート
--report オプションを使用して結果を Better I18N ダッシュボードにアップロードし、履歴追跡、傾向分析、およびチーム全体での i18n の健全性可視化を実現します。
# GitHub Actions example
- run: npx @better-i18n/cli doctor --ci --reportコマンド
どのコマンドをいつ使うか
Doctorは包括的な選択肢です。特定のチェックが必要な場合や、コミット前のフックでより迅速なフィードバックが必要な場合には、焦点を絞ったコマンドを使用してください。
医師5つの分析レイヤーによる完全な健全性スコア — プロジェクトの国際化ステータスに関する唯一の信頼できる情報源です。
スキャンハードコードされた文字列の集中検出。コミット前フック用に --staged をサポート。
確認ガイド付きプロンプトによる、欠落または未使用の翻訳キーのインタラクティブチェッカー。
同期ローカルからリモートへの完全な比較で、欠落しているキーと未使用のキーを同時に表示します。
機能
実世界の国際化ワークフロー向けに構築
健康スコア 0～100
カテゴリ別の内訳とCI合格/不合格閾値を含む単一スコア。翻訳の健全性を経時的に追跡します。
語彙的スコープ追跡
useTranslationsとgetTranslationsの両方に対するスマートな名前空間検出。すべてのt()呼び出しは正しい名前空間にマッピングされます。
サーバーコンポーネントサポート
Next.js App Routerの非同期サーバー関数を完全にサポート。サーバーサイドのgetTranslations呼び出しを検知し監査します。
設定可能なルール
i18n.config.ts 内のルールを無効化またはレベルダウンします。プロジェクトの要件に合わせてルールを「error」、「warning」、または「off」に設定してください。
スマートフィルタリング
CSSクラス名、URL、インポートパス、開発者定数は自動的に無視されます。実行可能な結果のみを表示します。
詳細監査ログ
--verbose オプションによる詳細な可視性。スコープ要約、タイミング情報、およびデバッグ用の名前空間解決トレース。