@intlayer/docs 9.5.2 → 9.5.4-canary.0

package/frequent_questions/en/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: How to limit Claude Code token consumption to generate translations
+description: Why translating with Claude Code burns tokens, what Intlayer does instead (filters translated keys, chunks JSON, translates markdown block by block), and how to reuse your Claude subscription with claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - token consumption
+  - setup-token
+  - i18n
+  - internationalization
+  - translation
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# How to limit Claude Code token consumption to generate translations
+
+## Problem Description
+
+Asking Claude Code (or any coding agent) to translate your content is the most expensive way to do it. For each run, the agent has to:
+
+- Load the complete JSON or content file into its context, even the keys that are already translated.
+- Search the related files to figure out where the content lives and how it is structured.
+- Work out which locales are missing and should be generated.
+- Re-read your custom instructions every time ("transform URLs this way", "keep the brand name in English", "use the informal form").
+- Rewrite the whole file, including the parts that did not change.
+
+All of that is re-sent on every turn, so the cost grows with `size of the content × number of locales × number of turns`, and any drift in formatting or keys has to be caught by hand.
+
+## What Intlayer does instead
+
+The interest of Intlayer is to do that work outside the agent, with a pipeline built for translation:
+
+- **Filters existing translations** to limit token usage. Keys already translated in your JSON are stripped out, and only the missing ones are sent to the model.
+- **Translates markdown block by block.** For documentation, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-review.md) compare each block with the base document and skip the blocks that are already translated or unchanged.
+- **Chunks your JSON** if it is too large, to stay in the best part of the context window.
+- **Flattens and reconstructs your JSON** to optimize token consumption.
+- **Inserts custom prompts** for specific rules regarding your brand and wording (`applicationContext`, `--custom-instructions`), so you write them once instead of repeating them in every conversation.
+- **Validates the structure** to ensure consistency and prevent key drift, and preserves formatting (markdown, HTML, insertions, plurals).
+- **Implements retry management** when the output is malformed.
+- **Queues and parallelizes requests** across files, chunks and locales to increase speed.
+
+None of that goes through the agent's context. The rule of thumb: let the agent decide **what** to internationalize, and let Intlayer do the repetitive work.
+
+## Solution
+
+### 1. Delegate extraction to `intlayer extract`
+
+Instead of asking the agent to rewrite each component by hand, let it run the [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md) command. It moves hard-coded strings into a `.content` file next to the component without loading the whole file into the agent's context.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegate translation to `intlayer fill`
+
+Never ask the agent to translate. The [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md) command applies the pipeline above: it only sends the missing keys, chunks them, runs the locales in parallel and writes the result back into your content files.
+
+```bash
+npx intlayer fill
+```
+
+A few flags keep the run small:
+
+- `--git-diff` (or `--uncommitted`) only processes the dictionaries changed in the current branch.
+- `--file` or `--keys` targets specific content files.
+- `--output-locales fr es` limits the run to the locales you actually need now.
+- `--skip-metadata` skips title, description and tags generation.
+- `--data-serialization toon` sends a more compact payload to the model (fewer tokens, slightly less consistent output).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Translate markdown with `doc translate` and `doc review`
+
+Asking an agent to translate a `.md` file means pasting the whole document, for every locale, on every change. The [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-review.md) commands work block by block instead.
+
+Use `doc translate` when the translated file does not exist yet. It chunks the markdown, translates it in parallel and writes the target files:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Use `doc review` when the translated file already exists. It compares each block with the base document, skips the blocks that are already translated or unchanged, and only sends the diverging ones:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Both commands accept your rules once, instead of you repeating them in every prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Two modes of `doc review` are useful when the agent still needs to be in the loop, without any AI call from Intlayer:
+
+- `--mode report` logs the blocks that need attention, with line numbers, so the agent only touches those blocks.
+- `--mode synthesis` only logs which documents are up to date and which still have blocks to edit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Let the agent call the CLI through the MCP server
+
+With the [Intlayer MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md), the agent answers from the current documentation and runs `intlayer fill` or `intlayer doc review` itself instead of re-implementing it in the conversation.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installing the [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md) with `npx intlayer init skills` also stops the agent from guessing the Intlayer API and re-reading the docs on every task.
+
+### 5. Reuse your Claude subscription with `claude setup-token`
+
+Running the i18n setup in your interactive Claude Code session keeps the whole conversation history in context. Move the heavy lifting to a short headless session instead.
+
+Generate a long-lived token from your Claude subscription:
+
+```bash
+claude setup-token
+```
+
+Store it as `CLAUDE_CODE_OAUTH_TOKEN` (in a `.env` file or your CI secrets), then reuse it for a one-shot session that runs the Intlayer commands:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+The session only carries that prompt and the command output, not your whole conversation. The same token works in the [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) to run `intlayer fill` on every pull request.
+
+> The token issued by `claude setup-token` authenticates Claude Code only. It cannot be used as an Anthropic API key in `ai.apiKey`. For the translation itself, `intlayer fill` uses your [Intlayer account](https://app.intlayer.org) (free tier included) or your own provider key configured in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
+
+## Summary
+
+| Task                    | Who does it              | Tokens in the agent context |
+| ----------------------- | ------------------------ | --------------------------- |
+| Decide what to localize | Claude Code              | Low                         |
+| Extract strings         | `intlayer extract`       | None                        |
+| Translate content       | `intlayer fill`          | None                        |
+| Translate documentation | `intlayer doc translate` | None                        |
+| Update documentation    | `intlayer doc review`    | None                        |
+| Run the commands        | Headless Claude Code     | Prompt + command output     |

package/frequent_questions/en-GB/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: How to limit Claude Code token consumption to generate translations
+description: Why translating with Claude Code burns tokens, what Intlayer does instead (filters translated keys, chunks JSON, translates markdown block by block), and how to reuse your Claude subscription with claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - token consumption
+  - setup-token
+  - i18n
+  - internationalisation
+  - translation
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# How to limit Claude Code token consumption to generate translations
+
+## Problem Description
+
+Asking Claude Code (or any coding agent) to translate your content is the most expensive way to do it. For each run, the agent has to:
+
+- Load the complete JSON or content file into its context, even the keys that are already translated.
+- Search the related files to figure out where the content lives and how it is structured.
+- Work out which locales are missing and should be generated.
+- Re-read your custom instructions every time ("transform URLs this way", "keep the brand name in English", "use the informal form").
+- Rewrite the whole file, including the parts that did not change.
+
+All of that is re-sent on every turn, so the cost grows with `size of the content × number of locales × number of turns`, and any drift in formatting or keys has to be caught by hand.
+
+## What Intlayer does instead
+
+The interest of Intlayer is to do that work outside the agent, with a pipeline built for translation:
+
+- **Filters existing translations** to limit token usage. Keys already translated in your JSON are stripped out, and only the missing ones are sent to the model.
+- **Translates markdown block by block.** For documentation, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-review.md) compare each block with the base document and skip the blocks that are already translated or unchanged.
+- **Chunks your JSON** if it is too large, to stay in the best part of the context window.
+- **Flattens and reconstructs your JSON** to optimise token consumption.
+- **Inserts custom prompts** for specific rules regarding your brand and wording (`applicationContext`, `--custom-instructions`), so you write them once instead of repeating them in every conversation.
+- **Validates the structure** to ensure consistency and prevent key drift, and preserves formatting (markdown, HTML, insertions, plurals).
+- **Implements retry management** when the output is malformed.
+- **Queues and parallelises requests** across files, chunks and locales to increase speed.
+
+None of that goes through the agent's context. The rule of thumb: let the agent decide **what** to internationalise, and let Intlayer do the repetitive work.
+
+## Solution
+
+### 1. Delegate extraction to `intlayer extract`
+
+Instead of asking the agent to rewrite each component by hand, let it run the [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md) command. It moves hard-coded strings into a `.content` file next to the component without loading the whole file into the agent's context.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegate translation to `intlayer fill`
+
+Never ask the agent to translate. The [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/fill.md) command applies the pipeline above: it only sends the missing keys, chunks them, runs the locales in parallel and writes the result back into your content files.
+
+```bash
+npx intlayer fill
+```
+
+A few flags keep the run small:
+
+- `--git-diff` (or `--uncommitted`) only processes the dictionaries changed in the current branch.
+- `--file` or `--keys` targets specific content files.
+- `--output-locales fr es` limits the run to the locales you actually need now.
+- `--skip-metadata` skips title, description and tags generation.
+- `--data-serialization toon` sends a more compact payload to the model (fewer tokens, slightly less consistent output).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Translate markdown with `doc translate` and `doc review`
+
+Asking an agent to translate a `.md` file means pasting the whole document, for every locale, on every change. The [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-review.md) commands work block by block instead.
+
+Use `doc translate` when the translated file does not exist yet. It chunks the markdown, translates it in parallel and writes the target files:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Use `doc review` when the translated file already exists. It compares each block with the base document, skips the blocks that are already translated or unchanged, and only sends the diverging ones:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Both commands accept your rules once, instead of you repeating them in every prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Two modes of `doc review` are useful when the agent still needs to be in the loop, without any AI call from Intlayer:
+
+- `--mode report` logs the blocks that need attention, with line numbers, so the agent only touches those blocks.
+- `--mode synthesis` only logs which documents are up to date and which still have blocks to edit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Let the agent call the CLI through the MCP server
+
+With the [Intlayer MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md), the agent answers from the current documentation and runs `intlayer fill` or `intlayer doc review` itself instead of re-implementing it in the conversation.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installing the [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md) with `npx intlayer init skills` also stops the agent from guessing the Intlayer API and re-reading the docs on every task.
+
+### 5. Reuse your Claude subscription with `claude setup-token`
+
+Running the i18n setup in your interactive Claude Code session keeps the whole conversation history in context. Move the heavy lifting to a short headless session instead.
+
+Generate a long-lived token from your Claude subscription:
+
+```bash
+claude setup-token
+```
+
+Store it as `CLAUDE_CODE_OAUTH_TOKEN` (in a `.env` file or your CI secrets), then reuse it for a one-shot session that runs the Intlayer commands:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+The session only carries that prompt and the command output, not your whole conversation. The same token works in the [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) to run `intlayer fill` on every pull request.
+
+> The token issued by `claude setup-token` authenticates Claude Code only. It cannot be used as an Anthropic API key in `ai.apiKey`. For the translation itself, `intlayer fill` uses your [Intlayer account](https://app.intlayer.org) (free tier included) or your own provider key configured in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md#ai-configuration).
+
+## Summary
+
+| Task                    | Who does it              | Tokens in the agent context |
+| ----------------------- | ------------------------ | --------------------------- |
+| Decide what to localise | Claude Code              | Low                         |
+| Extract strings         | `intlayer extract`       | None                        |
+| Translate content       | `intlayer fill`          | None                        |
+| Translate documentation | `intlayer doc translate` | None                        |
+| Update documentation    | `intlayer doc review`    | None                        |
+| Run the commands        | Headless Claude Code     | Prompt + command output     |

package/frequent_questions/es/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Cómo limitar el consumo de tokens de Claude Code para generar traducciones
+description: Por qué traducir con Claude Code consume tokens innecesariamente, qué hace Intlayer en su lugar (filtra claves traducidas, fragmenta JSON, traduce markdown bloque por bloque) y cómo reutilizar tu suscripción a Claude con claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - consumo de tokens
+  - setup-token
+  - i18n
+  - internacionalización
+  - traducción
+  - fill
+  - mcp
+  - agente
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Cómo limitar el consumo de tokens de Claude Code para generar traducciones
+
+## Descripción del problema
+
+Pedirle a Claude Code (o a cualquier agente de desarrollo) que traduzca tu contenido es la forma más costosa de hacerlo. En cada ejecución, el agente debe:
+
+- Cargar el archivo JSON o de contenido completo en su contexto, incluso las claves que ya están traducidas.
+- Buscar en los archivos relacionados para identificar dónde reside el contenido y cómo está estructurado.
+- Determinar qué locales faltan y deben generarse.
+- Releer tus instrucciones personalizadas en cada ocasión ("transforma las URLs de este modo", "mantén el nombre de la marca en inglés", "utiliza un tono informal").
+- Reescribir el archivo completo, incluidas las partes que no cambiaron.
+
+Todo esto se reenvía en cada turno, por lo que el coste aumenta según `tamaño del contenido × número de locales × número de turnos`, y cualquier desviación en el formato o las claves debe corregirse a mano.
+
+## Qué hace Intlayer en su lugar
+
+La ventaja de Intlayer es que realiza este trabajo fuera del agente, mediante un pipeline especialmente diseñado para la traducción:
+
+- **Filtra las traducciones existentes** para limitar el consumo de tokens. Las claves ya traducidas en tu JSON se descartan, y solo se envían al modelo las faltantes.
+- **Traduce markdown bloque por bloque.** Para la documentación, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/doc-translate.md) y [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/doc-review.md) comparan cada bloque con el documento base y omiten los bloques ya traducidos o sin cambios.
+- **Fragmenta tu JSON (chunking)** si es demasiado grande, manteniéndose en la zona óptima de la ventana de contexto.
+- **Aplana y reconstruye tu JSON** para optimizar el consumo de tokens.
+- **Inserta prompts personalizados** para reglas específicas de tu marca y estilo (`applicationContext`, `--custom-instructions`), de forma que los escribes una sola vez en lugar de repetirlos en cada conversación.
+- **Valida la estructura** para garantizar la coherencia y evitar desviaciones de claves, preservando el formato (markdown, HTML, inserciones, plurales).
+- **Implementa gestión de reintentos (retry)** cuando la salida presenta un formato incorrecto.
+- **Pone en cola y paraleliza solicitudes** entre archivos, fragmentos y locales para acelerar el proceso.
+
+Nada de esto pasa por el contexto del agente. La regla básica: deja que el agente decida **qué** internacionalizar, y deja que Intlayer se encargue de la tarea repetitiva.
+
+## Solución
+
+### 1. Delegar la extracción a `intlayer extract`
+
+En lugar de pedirle al agente que reescriba cada componente a mano, haz que ejecute el comando [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/extract.md). Este traslada las cadenas fijas a un archivo `.content` junto al componente sin cargar todo el archivo en el contexto del agente.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegar la traducción a `intlayer fill`
+
+Nunca le pidas al agente que traduzca. El comando [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/fill.md) aplica el pipeline descrito: solo envía las claves faltantes, las fragmenta, procesa los locales en paralelo y escribe el resultado de nuevo en tus archivos de contenido.
+
+```bash
+npx intlayer fill
+```
+
+Algunos flags permiten mantener la ejecución acotada:
+
+- `--git-diff` (o `--uncommitted`) procesa únicamente los diccionarios modificados en la rama actual.
+- `--file` o `--keys` apunta a archivos de contenido específicos.
+- `--output-locales fr es` limita la ejecución a los locales que realmente necesitas ahora.
+- `--skip-metadata` omite la generación de título, descripción y etiquetas.
+- `--data-serialization toon` envía una carga útil más compacta al modelo (menos tokens, salida ligeramente menos predecible).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Traducir markdown con `doc translate` y `doc review`
+
+Pedirle a un agente que traduzca un archivo `.md` implica pegar el documento entero, para cada locale, en cada cambio. Los comandos [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/doc-translate.md) y [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/doc-review.md) operan en su lugar bloque por bloque.
+
+Utiliza `doc translate` cuando el archivo traducido aún no exista. Fragmenta el markdown, lo traduce en paralelo y escribe los archivos de destino:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Utiliza `doc review` cuando el archivo traducido ya exista. Compara cada bloque con el documento base, omite los bloques ya traducidos o sin cambios, y solo envía los divergentes:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Ambos comandos aceptan tus reglas una sola vez, sin necesidad de repetirlas en cada prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dos modos de `doc review` resultan prácticos cuando el agente necesita intervenir sin requerir llamadas de IA por parte de Intlayer:
+
+- `--mode report` muestra los bloques que requieren atención junto con sus números de línea, de modo que el agente solo toque esos bloques.
+- `--mode synthesis` reporta únicamente qué documentos están al día y cuáles tienen bloques pendientes de edición.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Permitir que el agente llame a la CLI mediante el servidor MCP
+
+Con el [servidor MCP de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/mcp_server.md), el agente responde basándose en la documentación actualizada y ejecuta `intlayer fill` o `intlayer doc review` por sí mismo en vez de reimplementar la lógica en la conversación.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Instalar las [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/agent_skills.md) con `npx intlayer init skills` también evita que el agente adivine la API de Intlayer y vuelva a leer la documentación en cada tarea.
+
+### 5. Reutilizar tu suscripción de Claude con `claude setup-token`
+
+Ejecutar la configuración de i18n en una sesión interactiva de Claude Code conserva todo el historial de la conversación en el contexto. Traslada ese trabajo pesado a una sesión corta en modo headless.
+
+Genera un token de larga duración a partir de tu suscripción de Claude:
+
+```bash
+claude setup-token
+```
+
+Guárdalo como `CLAUDE_CODE_OAUTH_TOKEN` (en un archivo `.env` o en los secretos de tu CI) y luego reutilízalo en una sesión puntual que ejecute los comandos de Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+La sesión solo contendrá ese prompt y la salida del comando, evitando todo el historial previo. El mismo token funciona en la [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) para ejecutar `intlayer fill` en cada pull request.
+
+> El token emitido por `claude setup-token` autentica únicamente a Claude Code. No se puede utilizar como clave de API de Anthropic en `ai.apiKey`. Para la traducción propiamente dicha, `intlayer fill` utiliza tu [cuenta de Intlayer](https://app.intlayer.org) (plan gratuito incluido) o tu propia clave de proveedor configurada en [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md#ai-configuration).
+
+## Resumen
+
+| Tarea                         | Quién la realiza             | Tokens en el contexto del agente |
+| ----------------------------- | ---------------------------- | -------------------------------- |
+| Decidir qué internacionalizar | Claude Code                  | Bajo                             |
+| Extraer cadenas               | `intlayer extract`           | Ninguno                          |
+| Traducir contenido            | `intlayer fill`              | Ninguno                          |
+| Traducir documentación        | `intlayer doc translate`     | Ninguno                          |
+| Actualizar documentación      | `intlayer doc review`        | Ninguno                          |
+| Ejecutar los comandos         | Claude Code en modo headless | Prompt + salida del comando      |

package/frequent_questions/fr/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Comment limiter la consommation de tokens de Claude Code pour générer des traductions
+description: Pourquoi traduire avec Claude Code consomme inutilement des tokens, ce qu'Intlayer fait à la place (filtre les clés traduites, découpe le JSON, traduit le markdown bloc par bloc), et comment réutiliser votre abonnement Claude avec claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - consommation de tokens
+  - setup-token
+  - i18n
+  - internationalisation
+  - traduction
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Comment limiter la consommation de tokens de Claude Code pour générer des traductions
+
+## Description du problème
+
+Demander à Claude Code (ou à tout agent de code) de traduire votre contenu est la façon la plus coûteuse de procéder. À chaque exécution, l'agent doit :
+
+- Charger l'intégralité du fichier JSON ou de contenu dans son contexte, même les clés déjà traduites.
+- Parcourir les fichiers associés pour déterminer où se trouve le contenu et comment il est structuré.
+- Identifier quelles locales sont manquantes et doivent être générées.
+- Relire vos instructions personnalisées à chaque fois ("transformer les URLs de cette façon", "conserver le nom de marque en anglais", "utiliser le tutoiement").
+- Réécrire l'ensemble du fichier, y compris les parties qui n'ont pas changé.
+
+Tout cela est réémis à chaque tour, ce qui fait croître le coût selon `taille du contenu × nombre de locales × nombre de tours`, et tout écart de formatage ou de clé doit être vérifié manuellement.
+
+## Ce qu'Intlayer fait à la place
+
+L'intérêt d'Intlayer est d'effectuer ce travail en dehors de l'agent, avec un pipeline spécialement conçu pour la traduction :
+
+- **Filtre les traductions existantes** pour limiter l'utilisation de tokens. Les clés déjà traduites dans votre JSON sont ignorées, et seules les clés manquantes sont envoyées au modèle.
+- **Traduit le markdown bloc par bloc.** Pour la documentation, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/doc-translate.md) et [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/doc-review.md) comparent chaque bloc avec le document de base et ignorent les blocs déjà traduits ou inchangés.
+- **Découpe votre JSON (chunking)** s'il est trop volumineux, afin de rester dans la partie optimale de la fenêtre de contexte.
+- **Aplatit et reconstruit votre JSON** pour optimiser la consommation de tokens.
+- **Insère des prompts personnalisés** pour les règles spécifiques liées à votre marque et à votre terminologie (`applicationContext`, `--custom-instructions`), vous permettant ainsi de les écrire une seule fois au lieu de les répéter à chaque conversation.
+- **Valide la structure** pour garantir la cohérence, prévenir la dérive des clés, et préserver le formatage (markdown, HTML, insertions, pluriels).
+- **Gère les nouvelles tentatives (retry)** lorsque la réponse est malformée.
+- **Met en file d'attente et踟 parallélise les requêtes** sur les fichiers, les morceaux et les locales pour augmenter la vitesse.
+
+Rien de tout cela ne transite par le contexte de l'agent. La règle d'or : laissez l'agent décider **quoi** internationaliser, et laissez Intlayer se charger du travail répétitif.
+
+## Solution
+
+### 1. Déléguer l'extraction à `intlayer extract`
+
+Au lieu de demander à l'agent de réécrire chaque composant à la main, laissez-le exécuter la commande [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/extract.md). Elle déplace les chaînes codées en dur vers un fichier `.content` à côté du composant sans charger tout le fichier dans le contexte de l'agent.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Déléguer la traduction à `intlayer fill`
+
+Ne demandez jamais à l'agent de traduire. La commande [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/fill.md) applique le pipeline décrit ci-dessus : elle n'envoie que les clés manquantes, les découpe en morceaux, traite les locales en parallèle et réécrit le résultat dans vos fichiers de contenu.
+
+```bash
+npx intlayer fill
+```
+
+Quelques options permettent de restreindre l'exécution :
+
+- `--git-diff` (ou `--uncommitted`) traite uniquement les dictionnaires modifiés dans la branche actuelle.
+- `--file` ou `--keys` cible des fichiers de contenu spécifiques.
+- `--output-locales fr es` restreint l'exécution aux locales dont vous avez réellement besoin pour le moment.
+- `--skip-metadata` ignore la génération du titre, de la description et des tags.
+- `--data-serialization toon` transmet une charge utile plus compacte au modèle (moins de tokens, sortie légèrement moins prévisible).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Traduire le markdown avec `doc translate` et `doc review`
+
+Demander à un agent de traduire un fichier `.md` oblige à coller le document complet, pour chaque locale, à chaque modification. Les commandes [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/doc-translate.md) et [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/doc-review.md) opèrent plutôt bloc par bloc.
+
+Utilisez `doc translate` lorsque le fichier traduit n'existe pas encore. Elle découpe le markdown, le traduit en parallèle et écrit les fichiers cibles :
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Utilisez `doc review` lorsque le fichier traduit existe déjà. Elle compare chaque bloc au document de base, ignore les blocs déjà traduits ou inchangés, et n'envoie que les blocs divergents :
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Les deux commandes acceptent vos règles une seule fois, au lieu de les répéter dans chaque invite :
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Deux modes de `doc review` sont utiles lorsque l'agent doit rester dans la boucle sans aucun appel IA de la part d'Intlayer :
+
+- `--mode report` affiche les blocs nécessitant une attention avec les numéros de ligne, afin que l'agent ne modifie que ces blocs.
+- `--mode synthesis` affiche uniquement les documents qui sont à jour et ceux qui contiennent encore des blocs à modifier.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Laisser l'agent appeler le CLI via le serveur MCP
+
+Grâce au [serveur MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/mcp_server.md), l'agent s'appuie sur la documentation à jour et exécute lui-même `intlayer fill` ou `intlayer doc review` au lieu de réimplémenter la logique dans la conversation.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installer les [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/agent_skills.md) avec `npx intlayer init skills` évite également à l'agent de deviner l'API Intlayer et de relire la documentation à chaque tâche.
+
+### 5. Réutiliser votre abonnement Claude avec `claude setup-token`
+
+Exécuter la configuration i18n dans votre session interactive Claude Code conserve tout l'historique de la conversation dans le contexte. Déplacez plutôt cette charge vers une courte session headless.
+
+Générez un token longue durée depuis votre abonnement Claude :
+
+```bash
+claude setup-token
+```
+
+Enregistrez-le en tant que `CLAUDE_CODE_OAUTH_TOKEN` (dans un fichier `.env` ou dans les secrets de votre CI), puis réutilisez-le pour une session unique qui exécute les commandes Intlayer :
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+La session ne contient que ce prompt et la sortie de la commande, sans tout l'historique de votre conversation. Le même token fonctionne dans la [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) pour exécuter `intlayer fill` sur chaque pull request.
+
+> Le token généré par `claude setup-token` authentifie uniquement Claude Code. Il ne peut pas être utilisé comme clé API Anthropic dans `ai.apiKey`. Pour la traduction elle-même, `intlayer fill` utilise votre [compte Intlayer](https://app.intlayer.org) (offre gratuite incluse) ou votre propre clé de fournisseur configurée dans [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md#ai-configuration).
+
+## Résumé
+
+| Tâche                          | Responsable                  | Tokens dans le contexte de l'agent |
+| ------------------------------ | ---------------------------- | ---------------------------------- |
+| Décider quoi internationaliser | Claude Code                  | Faible                             |
+| Extraire les chaînes           | `intlayer extract`           | Aucun                              |
+| Traduire le contenu            | `intlayer fill`              | Aucun                              |
+| Traduire la documentation      | `intlayer doc translate`     | Aucun                              |
+| Mettre à jour la documentation | `intlayer doc review`        | Aucun                              |
+| Exécuter les commandes         | Claude Code en mode headless | Prompt + sortie de la commande     |