翻訳生成時のClaude Codeのトークン消費を抑える方法

問題の説明

Claude Code（またはその他のコーディングエージェント）にコンテンツの翻訳を依頼することは、最もコストのかかる方法です。実行するたびに、エージェントは以下の処理を行う必要があります。

• 既に翻訳済みのキーを含め、JSONやコンテンツファイル全体をコンテキストに読み込む。
• 関連ファイルを検索して、コンテンツの配置場所や構造を把握する。
• どのロケールが不足しており、生成すべきかを特定する。
• カスタム指示（「URLはこのように変換する」「ブランド名は英語のままにする」「親しみやすい表現を使う」など）を毎回再読込する。
• 変更されていない部分を含めて、ファイル全体を書き直す。

これらすべてがターンごとに再送信されるため、コストは「コンテンツのサイズ × ロケール数 × ターン数」で増加し、フォーマットやキーのずれを手動で検出して修正しなければならなくなります。

Intlayerが代わりに行うこと

Intlayerの大きなメリットは、翻訳専用に構築されたパイプラインによって、エージェントの外部でこれらの作業を実行することです。

• 既存の翻訳をフィルタリングしてトークン使用量を制限します。JSON内の既に翻訳されているキーは除外され、不足しているキーのみがモデルに送信されます。
• Markdownをブロック単位で翻訳します。 ドキュメントの場合、doc translate および doc review は各ブロックをベースドキュメントと比較し、すでに翻訳されているブロックや変更のないブロックをスキップします。
• JSONが大きすぎる場合はチャンクに分割し、コンテキストウィンドウの最適な範囲を維持します。
• JSONをフラット化して再構築し、トークン消費を最適化します。
• カスタムプロンプトを挿入してブランドや表現に関するルール（applicationContext, --custom-instructions）を適用できるため、会話ごとに繰り返すことなく一度だけ記述すれば済みます。
• 構造を検証して一貫性を担保し、キーのずれを防ぎながら、フォーマット（Markdown、HTML、挿入タグ、複数形など）を保持します。
• リトライ管理を実装し、出力が不正な場合に自動で再試行します。
• リクエストをキューイングして並列化し、ファイル、チャンク、ロケールをまたいで処理速度を向上させます。

これらの処理はエージェントのコンテキストを経由しません。基本原則として、エージェントには何を国際化するかを判断させ、定型的な反復作業はIntlayerに任せます。

解決策

1. 抽出を intlayer extract に任せる

エージェントに各コンポーネントを手動で書き直させる代わりに、extract コマンドを実行させます。ファイル全体をエージェントのコンテキストに読み込むことなく、ハードコードされた文字列をコンポーネントの隣にある .content ファイルへ移動します。

npx intlayer extract --file src/components/Header.tsx

2. 翻訳を intlayer fill に任せる

エージェントに直接翻訳させないでください。fill コマンドは上記のパイプラインを適用し、不足しているキーのみを送信してチャンク化し、ロケールを並列処理して結果をコンテンツファイルに書き戻します。

npx intlayer fill

実行範囲を絞り込むための便利なフラグがあります。

• --git-diff（または --uncommitted）: 現在のブランチで変更された辞書のみを処理します。
• --file または --keys: 特定のコンテンツファイルを対象にします。
• --output-locales fr es: 今すぐ必要なロケールのみに限定します。
• --skip-metadata: タイトル、説明、タグの生成をスキップします。
• --data-serialization toon: よりコンパクトなペイロードをモデルに送信します（トークン数が削減されますが、出力の再現性がわずかに低下する場合があります）。

npx intlayer fill --git-diff --output-locales fr es --skip-metadata

3. Markdownを doc translate と doc review で翻訳する

エージェントに .md ファイルの翻訳を依頼すると、変更のたびに全ロケール分のドキュメント全体を貼り付けることになります。対照的に、doc translate および doc review コマンドはブロック単位で動作します。

翻訳先ファイルがまだ存在しない場合は doc translate を使用します。Markdownをチャンク化し、並列で翻訳して対象ファイルを生成します。

npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

翻訳先ファイルが既に存在する場合は doc review を使用します。ベースドキュメントと各ブロックを比較し、翻訳済みまたは変更のないブロックをスキップして、差分のあるブロックのみを送信します。

npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

どちらのコマンドもルールを一度指定するだけでよく、プロンプトごとに繰り返す必要はありません。

npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."

IntlayerからのAI呼び出しを発生させずにエージェントをワークフローに参加させたい場合、doc review の以下の2つのモードが役立ちます。

• --mode report: 対応が必要なブロックを行番号と共に出力し、エージェントが該当ブロックのみを編集できるようにします。
• --mode synthesis: どのドキュメントが最新で、どれに編集対象ブロックが残っているかのみを出力します。

npx intlayer doc review --mode report --locales fr

4. エージェントにMCPサーバー経由でCLIを呼び出させる

Intlayer MCPサーバーを利用すると、エージェントは最新のドキュメントを参照し、会話内で独自に処理を再実装する代わりに intlayer fill や intlayer doc review を直接実行します。

claude mcp add intlayer npx -y @intlayer/mcp

npx intlayer init skills で Agent Skills を導入すると、エージェントがIntlayerのAPIを推測したり、タスクごとにドキュメントを読み直したりする無駄も防げます。

5. claude setup-token でClaudeのサブスクリプションを再利用する

対話型のClaude Codeセッション内でi18nのセットアップを実行すると、会話履歴全体がコンテキストに保持され続けます。負荷の大きい処理は、短時間のヘッドレスセッションに切り替えて実行しましょう。

お使いのClaudeサブスクリプションから長期トークンを発行します。

claude setup-token

これを CLAUDE_CODE_OAUTH_TOKEN として保存し（.env ファイルまたはCIのシークレット環境変数）、Intlayerコマンドを実行するワンショットセッションで再利用します。

CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"

このセッションは指定したプロンプトとコマンド出力のみを保持し、過去の全会話履歴を持ち越しません。同じトークンは Claude Code GitHub Action でも動作し、Pull Requestごとに intlayer fill を実行できます。

claude setup-token で発行されるトークンはClaude Code専用の認証トークンです。ai.apiKey のAnthropic APIキーとしては使用できません。翻訳処理自体には、Intlayerアカウント（無料枠あり）または ai で設定したプロバイダーのAPIキーが使用されます。

まとめ