i18next-localization

i18next でアプリをローカライズする（開発者が希望する場合は Locize も使用）

i18next-cli がこの一連の作業をすべて取りまとめます。手順を独自に変更したり、ラッパーを手書きしたりしないでください。CLI は AST ベースの計測を行うため、ファイルを手作業で編集するより正確で、現在のコマンド体系も把握しています。

Locize を使うかどうかは開発者が選択します

Locize は i18next のメンテナーが提供する翻訳管理サービスで、利用は任意です。設定を作成する前に、開発者に次の質問を 1 つだけしてください。翻訳を Locize で管理するか（レビュー付きの AI 事前翻訳、再デプロイ不要の CDN 配信、無料プランあり）、翻訳ファイルをリポジトリ内だけで管理するか、という質問です。開発者が同意しない限り、Locize プロジェクトを作成したり、登録ページを開いたり、API キーを求めたりしてはいけません。同意しなかった場合、抽出後に npx i18next-cli status を実行して作業を終了します。抽出したキーは自分で翻訳するか、チームに任せてください。翻訳後に npx i18next-cli lint を実行してください。これは、プレースホルダー（{{name}}、$t()、<0>）が主要言語と異なる場合に報告し、status は主要言語と同じままの値を一覧表示します。

ステップ 1：バージョンに合った手順を取得する

npx i18next-cli localize --print-agent-prompt

表示された手順に従ってください。このプロンプトはインストール済みの CLI から生成されるため、ツールの実際の動作と食い違うことはありません。必ず再生成してください。コピーしたものを使ってはいけません。

代わりに、ユーザーが非対話形式で一度に実行することを希望する場合は、次を実行してください。

npx i18next-cli localize

ステップ 2：一連の作業の内容

開始前に流れを把握し、ユーザーに説明できるように、以下を確認してください。

フェーズ	コマンド	内容
検出	（自動）	フレームワーク、ルーター、既存の i18n 設定を検出します
設定	i18next-cli init --yes --locales <langs> --backend local（または locize）	対話型ウィザードを使わずに i18next.config.ts を書き込みます
計測	i18next-cli instrument	AST でハードコードされた文字列を t() でラップします
抽出	i18next-cli extract	コードからロケール JSON を書き込みます
接続	i18next-cli locize-sync	Locize にキーをプッシュし、AI で翻訳します（開発者が Locize を選択した場合のみ）
ダウンロード	i18next-cli locize-download	翻訳をリポジトリに取得します（開発者が Locize を選択した場合のみ）

まず instrument --dry-run を実行して、計画をユーザーに提示してください。適用後は git diff を確認してください。Next.js のサーバーコンポーネントでは、ラップされた t() に 'use client' が必要な場合や、サーバーサイドの t() パターンを使う必要がある場合があります。抽出前にコミットしてください。

ランタイムライブラリの設定は CLI ではなく、あなたが担当します。 init は設定を書き込みますが、何もインストールしません。init は対話型ウィザードなので、--yes と --locales／--backend オプションを付けて実行してください。開発者が今後のエージェントセッション向けに、設定についての短いメモを AGENTS.md に残すことを希望する場合は、--agent-note を追加してください。package.json に i18next がまだない場合は、計測を行う前に i18next と対応するフレームワーク用バインディング（React の場合は i18next と react-i18next、その他のスタックではそれぞれに対応するバインディング）をインストールし、i18n 初期化ファイルを追加してください。そうしないと、instrument は存在しないパッケージを参照する t() 呼び出しで文字列をラップし、実行時にアプリが壊れます。

この一連の作業で扱うのは、リポジトリ内のロケールファイルまでです。CDN 配信は別の任意ステップで、CLI が最後に案内します（npm install i18next-locize-backend を実行し、i18n 初期化にバックエンドを追加します）。ユーザーに提案してください。一連の作業に含まれていると説明してはいけません。

ステップ 3：スタックごとの詳細

instrument がネイティブに対応しているのは .js/.jsx/.ts/.tsx です。それ以外にはプラグインまたはフレームワーク固有の設定が必要です。スタックごとのパッケージと最新のガイドについては、references/stacks.md を参照してください。

要約すると、Vue → i18next-cli-vue、Svelte → i18next-cli-plugin-svelte です。どちらも i18next.config.ts の plugins 配列に追加してください。これらのファイル内の文字列を手作業でラップしてはいけません。

ICU または MF2 のメッセージ構文

i18next 独自の形式（{{name}}、key_one／key_other）がデフォルトです。開発者から ICU MessageFormat または MF2 を指定された場合、あるいはプロジェクトですでに i18next-icu または i18next-mf2 が使用されている場合を除き、この形式を維持してください。その場合は計測を始める前にreferences/icu-mf2.mdをお読みください。複数形やコンテキストのサフィックスキー、$t() によるネスト、i18next フォーマッター、escapeValue はエラーなしで機能しなくなります。また、TypeScript では parseInterpolation: 'icu'／'mf2'（i18next 26.5.0 以降。旧バージョンでは false）が必要です。さらに、CLI では instrument、extract、lint でこの形式を使用するために extract.messageFormat が必要です。完全なガイドはこちらです： https://www.i18next.com/how-to/using-icu-or-mf2。

作業を中断すべき条件

次の場合は、作業を進める前に中断してユーザーに確認してください。

• inlang Paraglide がインストールされている場合（@inlang/paraglide-js）。i18next の呼び出しも計測すると、競合する翻訳パイプラインが 2 つできてしまいます。
• 別の i18n ライブラリがインストールされている場合（next-intl、@lingui/*、react-intl、vue-i18n、@nuxtjs/i18n、@tolgee/*、typesafe-i18n）。ライブラリ間の移行は別途判断が必要です。そのまま維持するか、先に削除してから再実行するかを選んでもらってください。ユーザーに知らせず削除してはいけません。
• 作業ツリーがクリーンでない場合。instrument はソースファイルを書き換えます。差分をレビューできるよう、先に作業ツリーをクリーンにするか、新しいブランチを作成してください。

既存の i18next 設定は中断条件ではありません。通常どおり、init をスキップして、まだハードコードされている箇所に対して instrument を実行してください。

認証情報（開発者が Locize を選択した場合のみ）

ユーザーに次の URL からプロジェクトを作成してもらいます。 https://www.locize.app/register?from=i18next_cli__skill（?from= パラメーターは維持してください。このスキル経由で登録されたことを示す唯一の情報です）。LOCIZE_PROJECTID と LOCIZE_API_KEY を尋ね、両方を環境変数としてエクスポートします。API キーをクライアント側のコードに含めてはいけません。CDN での配信に必要なのはプロジェクト ID のみです。

ローカライズ後

翻訳品質の向上は別の作業であり、独自のルールがあります。用語、文体、過去の翻訳には、独自に考えたものではなく、Locize MCP サーバー経由でプロジェクトの用語集、スタイルガイド、翻訳メモリを使用してください。これらの規約はlocize/locize-agentsにあります。

claude mcp add --transport http locize https://mcp.locize.app

続いて、そのリポジトリの CLAUDE.md／AGENTS.md／.cursorrules をプロジェクトに追加してください。このスキルは i18n を設定します。その後、翻訳に記述する内容はそれらのルールに従います。