@intlayer/docs 9.5.2 → 9.5.3

package/frequent_questions/it/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Come limitare il consumo di token di Claude Code per generare traduzioni
+description: Perché tradurre con Claude Code spreca token, cosa fa invece Intlayer (filtra le chiavi già tradotte, suddivide il JSON in blocchi, traduce il markdown blocco per blocco) e come riutilizzare il tuo abbonamento Claude con claude setup-token.
+keywords:
+  - claude code
+  - token
+  - consumo di token
+  - setup-token
+  - i18n
+  - internazionalizzazione
+  - traduzione
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Come limitare il consumo di token di Claude Code per generare traduzioni
+
+## Descrizione del problema
+
+Chiedere a Claude Code (o a qualsiasi agente di sviluppo) di tradurre i tuoi contenuti è il modo più costoso in assoluto. A ogni esecuzione, l'agente deve:
+
+- Caricare l'intero file JSON o di contenuto nel suo contesto, comprese le chiavi già tradotte.
+- Cercare nei file correlati per capire dove si trova il contenuto e come è strutturato.
+- Individuare quali locale mancano e devono essere generate.
+- Rileggere ogni volta le tue istruzioni personalizzate ("trasforma gli URL in questo modo", "mantieni il nome del brand in inglese", "usa una forma informale").
+- Riscrivere l'intero file, incluse le parti rimaste invariate.
+
+Tutto questo viene reinviato a ogni iterazione, quindi il costo cresce in base a `dimensione del contenuto × numero di locale × numero di iterazioni`, e ogni minima divergenza di formattazione o di chiavi deve essere controllata manualmente.
+
+## Cosa fa invece Intlayer
+
+Il vantaggio di Intlayer è svolgere questo lavoro al di fuori dell'agente, grazie a una pipeline progettata specificamente per la traduzione:
+
+- **Filtra le traduzioni esistenti** per limitare l'uso dei token. Le chiavi già tradotte nel tuo JSON vengono escluse, inviando al modello solo quelle mancanti.
+- **Traduce il markdown blocco per blocco.** Per la documentazione, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-review.md) confrontano ogni blocco con il documento base e saltano i blocchi già tradotti o invariati.
+- **Suddivide il tuo JSON in chunk** se è troppo grande, per operare nella parte migliore della finestra di contesto.
+- **Appiattisce e ricostruisce il tuo JSON** per ottimizzare il consumo di token.
+- **Inserisce prompt personalizzati** per regole specifiche sul tuo brand e stile (`applicationContext`, `--custom-instructions`), così da scriverli una sola volta invece di ripeterli in ogni conversazione.
+- **Valida la struttura** per assicurare coerenza, prevenire la deviazione delle chiavi e preservare la formattazione (markdown, HTML, inserimenti, plurali).
+- **Implementa la gestione dei tentativi (retry)** quando l'output è malformato.
+- **Accoda e parallelizza le richieste** tra file, blocchi e locale per massimizzare la velocità.
+
+Niente di tutto questo passa attraverso il contesto dell'agente. La regola d'oro: lascia che l'agente decida **cosa** internazionalizzare, e lascia a Intlayer il lavoro ripetitivo.
+
+## Soluzione
+
+### 1. Delegare l'estrazione a `intlayer extract`
+
+Invece di chiedere all'agente di riscrivere ogni componente a mano, fagli eseguire il comando [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/extract.md). Questo sposta le stringhe hardcoded in un file `.content` accanto al componente senza caricare l'intero file nel contesto dell'agente.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegare la traduzione a `intlayer fill`
+
+Non chiedere mai all'agente di tradurre direttamente. Il comando [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/fill.md) applica la pipeline sopra descritta: invia solo le chiavi mancanti, le suddivide, elabora le locale in parallelo e riscrive il risultato direttamente nei file di contenuto.
+
+```bash
+npx intlayer fill
+```
+
+Alcuni flag consentono di contenere l'elaborazione:
+
+- `--git-diff` (o `--uncommitted`) elabora solo i dizionari modificati nel branch corrente.
+- `--file` o `--keys` punta a file di contenuto specifici.
+- `--output-locales fr es` limita l'esecuzione alle sole locale necessarie al momento.
+- `--skip-metadata` ignora la generazione di titolo, descrizione e tag.
+- `--data-serialization toon` invia un payload più compatto al modello (meno token, output leggermente meno prevedibile).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Tradurre il markdown con `doc translate` e `doc review`
+
+Chiedere a un agente di tradurre un file `.md` comporta l'inclusione dell'intero documento, per ogni locale, a ogni modifica. I comandi [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-review.md) lavorano invece blocco per blocco.
+
+Usa `doc translate` quando il file tradotto non esiste ancora. Suddivide il markdown, lo traduce in parallelo e crea i file di destinazione:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Usa `doc review` quando il file tradotto esiste già. Confronta ogni blocco con il documento base, salta i blocchi già tradotti o invariati e invia solo quelli divergenti:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Entrambi i comandi accettano le tue regole una volta sola, senza doverle ripetere in ogni prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Due modalità di `doc review` sono utili quando l'agente deve rimanere coinvolto nel flusso, senza alcuna chiamata AI da parte di Intlayer:
+
+- `--mode report` segnala i blocchi che richiedono attenzione, completi di numero di riga, in modo che l'agente modifichi solo quei blocchi.
+- `--mode synthesis` riporta unicamente quali documenti sono aggiornati e quali presentano ancora blocchi da modificare.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Far chiamare la CLI all'agente tramite il server MCP
+
+Grazie al [server MCP di Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/mcp_server.md), l'agente risponde basandosi sulla documentazione aggiornata ed esegue autonomamente `intlayer fill` o `intlayer doc review`, invece di dover reimplementare la logica nella conversazione.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installare le [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/agent_skills.md) con `npx intlayer init skills` evita inoltre che l'agente debba indovinare l'API di Intlayer e rileggere la documentazione a ogni task.
+
+### 5. Riutilizzare l'abbonamento Claude con `claude setup-token`
+
+Eseguire la configurazione di i18n nella sessione interattiva di Claude Code mantiene l'intera cronologia della conversazione nel contesto. Sposta invece questo carico di lavoro su una breve sessione headless.
+
+Genera un token a lunga durata dal tuo abbonamento Claude:
+
+```bash
+claude setup-token
+```
+
+Salvalo come `CLAUDE_CODE_OAUTH_TOKEN` (in un file `.env` o nei secret della tua CI), quindi riutilizzalo per una sessione mirata che esegua i comandi Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+La sessione conterrà solo quel prompt e l'output del comando, evitando tutta la cronologia precedente. Lo stesso token funziona nella [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) per eseguire `intlayer fill` su ogni pull request.
+
+> Il token generato da `claude setup-token` autentica unicamente Claude Code. Non può essere usato come chiave API Anthropic in `ai.apiKey`. Per la traduzione vera e propria, `intlayer fill` usa il tuo [account Intlayer](https://app.intlayer.org) (piano gratuito incluso) o la tua chiave fornitore configurata in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#ai-configuration).
+
+## Riepilogo
+
+| Attività                     | Chi la esegue                    | Token nel contesto dell'agente |
+| ---------------------------- | -------------------------------- | ------------------------------ |
+| Decidere cosa localizzare    | Claude Code                      | Basso                          |
+| Estrarre le stringhe         | `intlayer extract`               | Nessuno                        |
+| Tradurre i contenuti         | `intlayer fill`                  | Nessuno                        |
+| Tradurre la documentazione   | `intlayer doc translate`         | Nessuno                        |
+| Aggiornare la documentazione | `intlayer doc review`            | Nessuno                        |
+| Eseguire i comandi           | Claude Code in modalità headless | Prompt + output del comando    |

package/frequent_questions/ja/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: 翻訳生成時のClaude Codeのトークン消費を抑える方法
+description: Claude Codeでの翻訳がトークンを浪費する理由、Intlayerが代わりに実行する処理（翻訳済みキーの除外、JSONのチャンク化、Markdownのブロック単位翻訳）、およびclaude setup-tokenでClaudeのサブスクリプションを再利用する方法。
+keywords:
+  - claude code
+  - tokens
+  - トークン消費
+  - setup-token
+  - i18n
+  - 国際化
+  - 翻訳
+  - fill
+  - mcp
+  - エージェント
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# 翻訳生成時のClaude Codeのトークン消費を抑える方法
+
+## 問題の説明
+
+Claude Code（またはその他のコーディングエージェント）にコンテンツの翻訳を依頼することは、最もコストのかかる方法です。実行するたびに、エージェントは以下の処理を行う必要があります。
+
+- 既に翻訳済みのキーを含め、JSONやコンテンツファイル全体をコンテキストに読み込む。
+- 関連ファイルを検索して、コンテンツの配置場所や構造を把握する。
+- どのロケールが不足しており、生成すべきかを特定する。
+- カスタム指示（「URLはこのように変換する」「ブランド名は英語のままにする」「親しみやすい表現を使う」など）を毎回再読込する。
+- 変更されていない部分を含めて、ファイル全体を書き直す。
+
+これらすべてがターンごとに再送信されるため、コストは「`コンテンツのサイズ × ロケール数 × ターン数`」で増加し、フォーマットやキーのずれを手動で検出して修正しなければならなくなります。
+
+## Intlayerが代わりに行うこと
+
+Intlayerの大きなメリットは、翻訳専用に構築されたパイプラインによって、エージェントの外部でこれらの作業を実行することです。
+
+- **既存の翻訳をフィルタリング**してトークン使用量を制限します。JSON内の既に翻訳されているキーは除外され、不足しているキーのみがモデルに送信されます。
+- **Markdownをブロック単位で翻訳します。** ドキュメントの場合、[`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-translate.md) および [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-review.md) は各ブロックをベースドキュメントと比較し、すでに翻訳されているブロックや変更のないブロックをスキップします。
+- **JSONが大きすぎる場合はチャンクに分割**し、コンテキストウィンドウの最適な範囲を維持します。
+- **JSONをフラット化して再構築**し、トークン消費を最適化します。
+- **カスタムプロンプトを挿入**してブランドや表現に関するルール（`applicationContext`, `--custom-instructions`）を適用できるため、会話ごとに繰り返すことなく一度だけ記述すれば済みます。
+- **構造を検証**して一貫性を担保し、キーのずれを防ぎながら、フォーマット（Markdown、HTML、挿入タグ、複数形など）を保持します。
+- **リトライ管理**を実装し、出力が不正な場合に自動で再試行します。
+- **リクエストをキューイングして並列化**し、ファイル、チャンク、ロケールをまたいで処理速度を向上させます。
+
+これらの処理はエージェントのコンテキストを経由しません。基本原則として、エージェントには**何を**国際化するかを判断させ、定型的な反復作業はIntlayerに任せます。
+
+## 解決策
+
+### 1. 抽出を `intlayer extract` に任せる
+
+エージェントに各コンポーネントを手動で書き直させる代わりに、[`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/extract.md) コマンドを実行させます。ファイル全体をエージェントのコンテキストに読み込むことなく、ハードコードされた文字列をコンポーネントの隣にある `.content` ファイルへ移動します。
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. 翻訳を `intlayer fill` に任せる
+
+エージェントに直接翻訳させないでください。[`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/fill.md) コマンドは上記のパイプラインを適用し、不足しているキーのみを送信してチャンク化し、ロケールを並列処理して結果をコンテンツファイルに書き戻します。
+
+```bash
+npx intlayer fill
+```
+
+実行範囲を絞り込むための便利なフラグがあります。
+
+- `--git-diff`（または `--uncommitted`）: 現在のブランチで変更された辞書のみを処理します。
+- `--file` または `--keys`: 特定のコンテンツファイルを対象にします。
+- `--output-locales fr es`: 今すぐ必要なロケールのみに限定します。
+- `--skip-metadata`: タイトル、説明、タグの生成をスキップします。
+- `--data-serialization toon`: よりコンパクトなペイロードをモデルに送信します（トークン数が削減されますが、出力の再現性がわずかに低下する場合があります）。
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Markdownを `doc translate` と `doc review` で翻訳する
+
+エージェントに `.md` ファイルの翻訳を依頼すると、変更のたびに全ロケール分のドキュメント全体を貼り付けることになります。対照的に、[`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-translate.md) および [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-review.md) コマンドはブロック単位で動作します。
+
+翻訳先ファイルがまだ存在しない場合は `doc translate` を使用します。Markdownをチャンク化し、並列で翻訳して対象ファイルを生成します。
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+翻訳先ファイルが既に存在する場合は `doc review` を使用します。ベースドキュメントと各ブロックを比較し、翻訳済みまたは変更のないブロックをスキップして、差分のあるブロックのみを送信します。
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+どちらのコマンドもルールを一度指定するだけでよく、プロンプトごとに繰り返す必要はありません。
+
+```bash
+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`: どのドキュメントが最新で、どれに編集対象ブロックが残っているかのみを出力します。
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. エージェントにMCPサーバー経由でCLIを呼び出させる
+
+[Intlayer MCPサーバー](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/mcp_server.md)を利用すると、エージェントは最新のドキュメントを参照し、会話内で独自に処理を再実装する代わりに `intlayer fill` や `intlayer doc review` を直接実行します。
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+`npx intlayer init skills` で [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/agent_skills.md) を導入すると、エージェントがIntlayerのAPIを推測したり、タスクごとにドキュメントを読み直したりする無駄も防げます。
+
+### 5. `claude setup-token` でClaudeのサブスクリプションを再利用する
+
+対話型のClaude Codeセッション内でi18nのセットアップを実行すると、会話履歴全体がコンテキストに保持され続けます。負荷の大きい処理は、短時間のヘッドレスセッションに切り替えて実行しましょう。
+
+お使いのClaudeサブスクリプションから長期トークンを発行します。
+
+```bash
+claude setup-token
+```
+
+これを `CLAUDE_CODE_OAUTH_TOKEN` として保存し（`.env` ファイルまたはCIのシークレット環境変数）、Intlayerコマンドを実行するワンショットセッションで再利用します。
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+このセッションは指定したプロンプトとコマンド出力のみを保持し、過去の全会話履歴を持ち越しません。同じトークンは [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) でも動作し、Pull Requestごとに `intlayer fill` を実行できます。
+
+> `claude setup-token` で発行されるトークンはClaude Code専用の認証トークンです。`ai.apiKey` のAnthropic APIキーとしては使用できません。翻訳処理自体には、[Intlayerアカウント](https://app.intlayer.org)（無料枠あり）または [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md#ai-configuration) で設定したプロバイダーのAPIキーが使用されます。
+
+## まとめ
+
+| タスク                 | 担当者                   | エージェントコンテキスト内のトークン |
+| ---------------------- | ------------------------ | ------------------------------------ |
+| ローカライズ対象の決定 | Claude Code              | 少量                                 |
+| 文字列の抽出           | `intlayer extract`       | なし                                 |
+| コンテンツの翻訳       | `intlayer fill`          | なし                                 |
+| ドキュメントの翻訳     | `intlayer doc translate` | なし                                 |
+| ドキュメントの更新     | `intlayer doc review`    | なし                                 |
+| コマンドの実行         | ヘッドレスClaude Code    | プロンプト + コマンド出力            |

package/frequent_questions/ko/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: 번역 생성 시 Claude Code 토큰 소모를 줄이는 방법
+description: Claude Code로 번역할 때 토큰이 낭비되는 이유와 Intlayer가 대신 수행하는 작업(번역된 키 필터링, JSON 청크 분할, 마크다운 블록 단위 번역), claude setup-token으로 Claude 구독을 재사용하는 방법을 알아봅니다.
+keywords:
+  - claude code
+  - tokens
+  - 토큰 소모
+  - setup-token
+  - i18n
+  - 국제화
+  - 번역
+  - fill
+  - mcp
+  - 에이전트
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# 번역 생성 시 Claude Code 토큰 소모를 줄이는 방법
+
+## 문제 설명
+
+Claude Code(또는 다른 코딩 에이전트)에 콘텐츠 번역을 직접 요청하는 것은 가장 비용이 많이 드는 방식입니다. 실행할 때마다 에이전트는 다음 작업을 반복해야 합니다.
+
+- 이미 번역된 키까지 포함하여 전체 JSON 또는 콘텐츠 파일을 컨텍스트에 로드합니다.
+- 관련 파일을 검색하여 콘텐츠의 위치와 구조를 파악합니다.
+- 누락된 로케일이 무엇인지, 무엇을 생성해야 하는지 파악합니다.
+- 매번 커스텀 지침("URL은 이런 방식으로 변환", "브랜드 이름은 영어로 유지", "친근한 어조 사용")을 다시 읽습니다.
+- 변경되지 않은 부분을 포함하여 파일 전체를 다시 작성합니다.
+
+이 모든 내용이 매 턴마다 다시 전송되므로 비용은 `콘텐츠 크기 × 로케일 수 × 턴 수`에 비례하여 증가하며, 서식이나 키의 불일치를 수작업으로 감지해야 합니다.
+
+## Intlayer가 대신 처리하는 작업
+
+Intlayer의 핵심 가치는 번역 전용 파이프라인을 통해 에이전트 외부에서 이 작업을 수행한다는 점입니다.
+
+- **기존 번역 필터링**으로 토큰 사용량을 제한합니다. JSON에서 이미 번역된 키는 제거되고, 누락된 키만 모델로 전달됩니다.
+- **마크다운을 블록 단위로 번역합니다.** 문서의 경우 [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-translate.md) 및 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-review.md)가 각 블록을 기본 문서와 비교하여 이미 번역되었거나 변경되지 않은 블록을 건너뜁니다.
+- **JSON이 너무 큰 경우 청크로 분할**하여 컨텍스트 윈도우의 최적 구간에 머무릅니다.
+- **JSON 평탄화 및 재구성**을 통해 토큰 소비를 최적화합니다.
+- **커스텀 프롬프트 삽입**을 지원하여 브랜드와 용어에 대한 특정 규칙(`applicationContext`, `--custom-instructions`)을 매 대화마다 반복하지 않고 한 번만 작성할 수 있습니다.
+- **구조 유효성 검사**를 수행하여 일관성을 보장하고 키 누락을 방지하며, 서식(마크다운, HTML, 삽입 태그, 복수형)을 보존합니다.
+- **재시도(retry) 관리**를 구현하여 출력이 잘못된 형식일 때 자동으로 복구합니다.
+- **요청 큐잉 및 병렬화**를 통해 파일, 청크, 로케일 전반의 처리 속도를 극대화합니다.
+
+이 중 어느 것도 에이전트의 컨텍스트를 거치지 않습니다. 기본 원칙은 에이전트가 **무엇을** 국제화할지 결정하게 하고, 반복적인 작업은 Intlayer에 맡기는 것입니다.
+
+## 해결 방법
+
+### 1. 추출 작업을 `intlayer extract`에 위임
+
+에이전트에게 각 컴포넌트를 수작업으로 다시 작성하도록 요청하는 대신 [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md) 명령을 실행하게 하세요. 전체 파일을 에이전트 컨텍스트에 올리지 않고도 하드코딩된 문자열을 컴포넌트 옆의 `.content` 파일로 옮겨줍니다.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. 번역 작업을 `intlayer fill`에 위임
+
+에이전트에게 직접 번역을 요청하지 마세요. [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/fill.md) 명령은 위에서 설명한 파이프라인을 적용합니다. 누락된 키만 전송하고 청크로 나누며 로케일을 병렬로 실행하여 결과를 콘텐츠 파일에 직접 반영합니다.
+
+```bash
+npx intlayer fill
+```
+
+몇 가지 플래그를 통해 실행 범위를 최소화할 수 있습니다.
+
+- `--git-diff`(또는 `--uncommitted`): 현재 브랜치에서 변경된 딕셔너리만 처리합니다.
+- `--file` 또는 `--keys`: 특정 콘텐츠 파일을 지정합니다.
+- `--output-locales fr es`: 현재 실제로 필요한 로케일로만 실행을 제한합니다.
+- `--skip-metadata`: 제목, 설명, 태그 생성을 건너뜁니다.
+- `--data-serialization toon`: 모델에 더 간결한 페이로드를 전달합니다(토큰 절약, 출력 일관성 소폭 변동 가능).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. `doc translate` 및 `doc review`로 마크다운 번역
+
+에이전트에게 `.md` 파일 번역을 요청하면 수정할 때마다 각 로케일별 전체 문서를 붙여넣어야 합니다. 반면 [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-translate.md) 및 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-review.md) 명령은 블록 단위로 동작합니다.
+
+번역 대상 파일이 아직 존재하지 않는 경우 `doc translate`를 사용하세요. 마크다운을 청크로 나누고 병렬로 번역하여 대상 파일을 생성합니다.
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+번역 대상 파일이 이미 존재하는 경우 `doc review`를 사용하세요. 각 블록을 기본 문서와 비교하여 이미 번역되었거나 변경되지 않은 블록은 건너뛰고, 차이가 있는 블록만 전달합니다.
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+두 명령 모두 프롬프트마다 반복할 필요 없이 규칙을 한 번만 전달하면 됩니다.
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Intlayer 측의 AI 호출 없이 에이전트가 검토 흐름에 참여해야 할 때는 `doc review`의 두 가지 모드가 유용합니다.
+
+- `--mode report`: 주의가 필요한 블록을 줄 번호와 함께 출력하여 에이전트가 해당 블록만 수정할 수 있도록 합니다.
+- `--mode synthesis`: 최신 상태인 문서와 아직 편집할 블록이 남아있는 문서의 목록만 출력합니다.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. 에이전트가 MCP 서버를 통해 CLI를 호출하도록 설정
+
+[Intlayer MCP 서버](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/mcp_server.md)를 사용하면 에이전트가 최신 문서를 기반으로 응답하며, 대화 내에서 직접 번역 로직을 구현하는 대신 `intlayer fill` 또는 `intlayer doc review`를 직접 실행합니다.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+`npx intlayer init skills`로 [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/agent_skills.md)를 설치하면 에이전트가 Intlayer API를 임의로 추측하거나 작업마다 문서를 다시 읽는 낭비도 방지할 수 있습니다.
+
+### 5. `claude setup-token`으로 Claude 구독 재사용
+
+대화형 Claude Code 세션에서 i18n 설정을 실행하면 전체 대화 내역이 컨텍스트에 누적됩니다. 부담이 큰 작업은 짧은 헤드리스(headless) 세션으로 전환하여 실행하세요.
+
+Claude 구독에서 장기 지속 토큰을 생성합니다.
+
+```bash
+claude setup-token
+```
+
+이를 `CLAUDE_CODE_OAUTH_TOKEN`으로 저장(환경 변수 `.env` 파일 또는 CI 시크릿)한 뒤, Intlayer 명령을 실행하는 단발성 세션에서 재사용합니다.
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+해당 세션은 전체 대화 내역 없이 해당 프롬프트와 명령 출력만 담게 됩니다. 동일한 토큰을 [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action)에서도 사용하여 모든 풀 리퀘스트마다 `intlayer fill`을 실행할 수 있습니다.
+
+> `claude setup-token`으로 발급된 토큰은 Claude Code 전용 인증 토큰입니다. `ai.apiKey`의 Anthropic API 키로는 사용할 수 없습니다. 번역 자체에는 [Intlayer 계정](https://app.intlayer.org)(무료 티어 포함)이나 [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md#ai-configuration)에 설정한 자체 제공업체 API 키가 사용됩니다.
+
+## 요약
+
+| 작업             | 담당                     | 에이전트 컨텍스트 내 토큰 |
+| ---------------- | ------------------------ | ------------------------- |
+| 현지화 대상 결정 | Claude Code              | 낮음                      |
+| 문자열 추출      | `intlayer extract`       | 없음                      |
+| 콘텐츠 번역      | `intlayer fill`          | 없음                      |
+| 문서 번역        | `intlayer doc translate` | 없음                      |
+| 문서 업데이트    | `intlayer doc review`    | 없음                      |
+| 명령 실행        | 헤드리스 Claude Code     | 프롬프트 + 명령 출력      |

package/frequent_questions/pl/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Jak ograniczyć zużycie tokenów Claude Code podczas generowania tłumaczeń
+description: Dlaczego tłumaczenie z Claude Code zużywa nadmierną liczbę tokenów, co zamiast tego robi Intlayer (filtruje przetłumaczone klucze, dzieli JSON na fragmenty, tłumaczy markdown blok po bloku) oraz jak ponownie wykorzystać subskrypcję Claude za pomocą claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - zużycie tokenów
+  - setup-token
+  - i18n
+  - internacjonalizacja
+  - tłumaczenie
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Jak ograniczyć zużycie tokenów Claude Code podczas generowania tłumaczeń
+
+## Opis problemu
+
+Zlecanie tłumaczenia treści narzędziu Claude Code (lub jakiemukolwiek innemu agentowi programistycznemu) jest najbardziej kosztownym podejściem. Przy każdym uruchomieniu agent musi:
+
+- Załadować cały plik JSON lub plik zawartości do swojego kontekstu, w tym klucze, które zostały już przetłumaczone.
+- Przeszukać powiązane pliki, aby ustalić, gdzie znajduje się treść i jak jest zorganizowana.
+- Określić, których wersji językowych (locales) brakuje i które należy wygenerować.
+- Za każdym razem ponownie odczytywać niestandardowe instrukcje ("przekształcaj adresy URL w ten sposób", "pozostaw nazwę marki po angielsku", "stosuj formę nieformalną").
+- Przepisać cały plik od nowa, łącznie z fragmentami, które w ogóle się nie zmieniły.
+
+Wszystkie te informacje są przesyłane ponownie w każdej turze konwersacji, przez co koszt rośnie według wzoru `rozmiar treści × liczba wersji językowych × liczba tur`, a wszelkie rozbieżności w formatowaniu lub kluczach trzeba wychwytywać ręcznie.
+
+## Co zamiast tego robi Intlayer
+
+Zaletą Intlayer jest wykonywanie tej pracy poza agentem, za pośrednictwem potoku stworzonego specjalnie do zadań tłumaczeniowych:
+
+- **Filtruje istniejące tłumaczenia**, aby ograniczyć zużycie tokenów. Klucze już przetłumaczone w pliku JSON są pomijane, a do modelu trafiają wyłącznie brakujące wpisy.
+- **Tłumaczy markdown blok po bloku.** W przypadku dokumentacji polecenia [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-translate.md) oraz [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-review.md) porównują każdy blok z dokumentem bazowym i pomijają bloki przetłumaczone lub niezmienione.
+- **Dzieli plik JSON na mniejsze fragmenty (chunking)**, jeśli jest zbyt duży, aby operować w optymalnej części okna kontekstu.
+- **Spłaszcza i rekonstruuje JSON**, optymalizując zużycie tokenów.
+- **Wstawia niestandardowe prompty** dla określonych zasad dotyczących marki i słownictwa (`applicationContext`, `--custom-instructions`), dzięki czemu definiujesz je raz, zamiast powtarzać w każdej rozmowie.
+- **Weryfikuje strukturę**, zapewniając spójność, zapobiegając rozbieżnościom kluczy i zachowując formatowanie (markdown, HTML, wstawki, formy mnogie).
+- **Zapewnia obsługę ponownych prób (retry)** w przypadku nieprawidłowego formatu odpowiedzi.
+- **Kolejkuje i zrównolegla żądania** pomiędzy plikami, fragmentami i językami, znacznie zwiększając szybkość działania.
+
+Żaden z tych procesów nie obciąża kontekstu agenta. Złota zasada: pozwól agentowi decydować, **co** zinternacjonalizować, a powtarzalną pracę powierz Intlayer.
+
+## Rozwiązanie
+
+### 1. Przekaż ekstrakcję poleceniu `intlayer extract`
+
+Zamiast prosić agenta o ręczne przepisywanie każdego komponentu, uruchom polecenie [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/extract.md). Przenosi ono zahardkodowane ciągi znaków do pliku `.content` obok komponentu, bez ładowania całego pliku do kontekstu agenta.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Przekaż tłumaczenie poleceniu `intlayer fill`
+
+Nigdy nie zlecaj tłumaczenia bezpośrednio agentowi. Polecenie [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/fill.md) stosuje wyżej opisany proces: wysyła wyłącznie brakujące klucze, dzieli je na części, przetwarza języki równolegle i zapisuje wynik z powrotem w plikach zawartości.
+
+```bash
+npx intlayer fill
+```
+
+Kilka flag pozwala utrzymać oszczędny zakres operacji:
+
+- `--git-diff` (lub `--uncommitted`) przetwarza tylko słowniki zmodyfikowane w bieżącej gałęzi.
+- `--file` lub `--keys` wskazuje konkretne pliki zawartości.
+- `--output-locales fr es` ogranicza wykonanie do języków, których faktycznie potrzebujesz w danym momencie.
+- `--skip-metadata` pomija generowanie tytułów, opisów i tagów.
+- `--data-serialization toon` przesyła bardziej zwarty ładunek danych do modelu (mniej tokenów, nieco mniej przewidywalny wynik).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Tłumacz markdown za pomocą `doc translate` i `doc review`
+
+Zlecenie agentowi przetłumaczenia pliku `.md` wiąże się z wklejaniem całego dokumentu dla każdego języka przy każdej zmianie. Z kolei polecenia [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-translate.md) i [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-review.md) operują blok po bloku.
+
+Używaj `doc translate`, gdy przetłumaczony plik jeszcze nie istnieje. Dzieli on markdown na części, tłumaczy je równolegle i generuje pliki docelowe:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Używaj `doc review`, gdy przetłumaczony plik już istnieje. Porównuje on każdy blok z dokumentem bazowym, pomija bloki przetłumaczone lub bez zmian i wysyła wyłącznie te różniące się:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Oba polecenia przyjmują Twoje wytyczne raz, bez potrzeby powtarzania ich w każdym monicie:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dwa tryby `doc review` są przydatne, gdy agent musi uczestniczyć w procesie bez wykonywania wywołań AI przez Intlayer:
+
+- `--mode report` raportuje bloki wymagające uwagi wraz z numerami linii, dzięki czemu agent modyfikuje tylko te konkretne fragmenty.
+- `--mode synthesis` informuje wyłącznie o tym, które dokumenty są aktualne, a które nadal zawierają bloki do edycji.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Pozwól agentowi wywoływać CLI za pośrednictwem serwera MCP
+
+Dzięki [serwerowi MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/mcp_server.md) agent odpowiada na podstawie aktualnej dokumentacji i samodzielnie uruchamia `intlayer fill` lub `intlayer doc review`, zamiast odtwarzać logikę w rozmowie.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Zainstalowanie [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/agent_skills.md) za pomocą `npx intlayer init skills` zapobiega ponadto zgadywaniu API Intlayer przez agenta i ponownemu czytaniu dokumentacji przy każdym zadaniu.
+
+### 5. Wykorzystaj ponownie subskrypcję Claude dzięki `claude setup-token`
+
+Wykonywanie konfiguracji i18n w interaktywnej sesji Claude Code utrzymuje całą historię rozmowy w oknie kontekstu. Przenieś to obciążenie do krótkiej sesji w trybie headless.
+
+Wygeneruj długoterminowy token w ramach swojej subskrypcji Claude:
+
+```bash
+claude setup-token
+```
+
+Zapisz go jako `CLAUDE_CODE_OAUTH_TOKEN` (w pliku `.env` lub w zmiennych CI), a następnie użyj go w jednorazowej sesji uruchamiającej polecenia Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Sesja obejmie wyłącznie ten prompt oraz wynik polecenia, bez obciążania wcześniejszą historią. Ten sam token działa w akcji [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action), umożliwiając uruchamianie `intlayer fill` przy każdym pull requeście.
+
+> Token wygenerowany przez `claude setup-token` uwierzytelnia wyłącznie Claude Code. Nie można go używać jako klucza Anthropic API w parametrze `ai.apiKey`. Do samego tłumaczenia `intlayer fill` wykorzystuje Twoje [konto Intlayer](https://app.intlayer.org) (w tym darmowy plan) lub własny klucz dostawcy skonfigurowany w sekcji [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md#ai-configuration).
+
+## Podsumowanie
+
+| Zadanie                   | Kto wykonuje             | Tokeny w kontekście agenta |
+| ------------------------- | ------------------------ | -------------------------- |
+| Decyzja o lokalizacji     | Claude Code              | Niskie                     |
+| Ekstrakcja ciągów znaków  | `intlayer extract`       | Brak                       |
+| Tłumaczenie zawartości    | `intlayer fill`          | Brak                       |
+| Tłumaczenie dokumentacji  | `intlayer doc translate` | Brak                       |
+| Aktualizacja dokumentacji | `intlayer doc review`    | Brak                       |
+| Uruchamianie poleceń      | Headless Claude Code     | Prompt + wynik polecenia   |