@intlayer/docs 9.5.2 → 9.5.3

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     |

package/frequent_questions/hi/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 या सामग्री फ़ाइल को अपने संदर्भ (context) में लोड करना पड़ता है।
+- सामग्री कहाँ स्थित है और इसकी संरचना कैसी है, यह समझने के लिए संबंधित फ़ाइलों को खोजना पड़ता है।
+- यह पता लगाना पड़ता है कि कौन से लोकेल अनुपलब्ध हैं और उन्हें उत्पन्न करने की आवश्यकता है।
+- आपके कस्टम निर्देशों को हर बार फिर से पढ़ना पड़ता है ("URL को इस तरह बदलें", "ब्रांड नाम अंग्रेजी में रखें", "अनौपचारिक रूप का उपयोग करें")।
+- उन हिस्सों सहित पूरी फ़ाइल को फिर से लिखना पड़ता है जिनमें कोई बदलाव नहीं हुआ था।
+
+यह सब प्रत्येक संवाद चक्र में फिर से भेजा जाता है, जिससे लागत `सामग्री का आकार × लोकेल की संख्या × चक्रों की संख्या` के अनुपात में बढ़ती है, और फ़ॉर्मेटिंग या कुंजियों में किसी भी अंतर को मैन्युअल रूप से ठीक करना पड़ता है।
+
+## Intlayer इसके बजाय क्या करता है
+
+Intlayer की सबसे बड़ी विशेषता यह है कि यह कार्य अनुवाद के लिए विशेष रूप से निर्मित पाइपलाइन के साथ एजेंट के बाहर किया जाता है:
+
+- **मौजूदा अनुवादों को फ़िल्टर करता है** ताकि टोकन का उपयोग सीमित रहे। आपके JSON में पहले से अनुवादित कुंजियों को हटा दिया जाता है, और केवल अनुपलब्ध कुंजियों को मॉडल को भेजा जाता है।
+- **Markdown का ब्लॉक-दर-ब्लॉक अनुवाद करता है।** प्रलेखन के लिए, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-translate.md) और [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-review.md) प्रत्येक ब्लॉक की तुलना मूल दस्तावेज़ से करते हैं और उन ब्लॉकों को छोड़ देते हैं जो पहले से अनुवादित या अपरिवर्तित हैं।
+- **यदि आपका JSON बहुत बड़ा है तो उसके टुकड़े (chunking) करता है**, ताकि संदर्भ विंडो के सबसे उपयुक्त भाग में रहा जा सके।
+- **टोकन खपत को अनुकूलित करने के लिए आपके JSON को समतल (flatten) और पुनर्गठित करता है**।
+- **कस्टम प्रॉम्प्ट सम्मिलित करता है** आपके ब्रांड और शब्दावली से संबंधित विशिष्ट नियमों के लिए (`applicationContext`, `--custom-instructions`), जिससे आप उन्हें हर बातचीत में दोहराने के बजाय केवल एक बार लिखते हैं।
+- **संरचना को मान्य करता है** ताकि निरंतरता सुनिश्चित हो सके और कुंजियों का भटकाव रुके, साथ ही फ़ॉर्मेटिंग (markdown, HTML, इंसर्शन, बहुवचन) सुरक्षित रहे।
+- **पुनः प्रयास प्रबंधन (retry)** लागू करता है यदि आउटपुट का प्रारूप अमान्य हो।
+- **गति बढ़ाने के लिए फ़ाइलों, टुकड़ों और लोकेल में अनुरोधों को कतारबद्ध और समानांतर करता है**।
+
+इनमें से कुछ भी एजेंट के संदर्भ से होकर नहीं गुजरता। मुख्य नियम: एजेंट को यह तय करने दें कि **क्या** अंतर्राष्ट्रीयकृत करना है, और दोहराए जाने वाले कार्य को Intlayer पर छोड़ दें।
+
+## समाधान
+
+### 1. निष्कर्षण को `intlayer extract` को सौंपें
+
+एजेंट को प्रत्येक घटक को हाथ से फिर से लिखने के लिए कहने के बजाय, उसे [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/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/hi/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` के साथ markdown का अनुवाद करें
+
+किसी एजेंट से `.md` फ़ाइल का अनुवाद करने के लिए कहने का अर्थ है प्रत्येक परिवर्तन पर, प्रत्येक लोकेल के लिए पूरा दस्तावेज़ चिपकाना। इसके विपरीत [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-translate.md) और [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/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."
+```
+
+`doc review` के दो मोड तब उपयोगी होते हैं जब एजेंट को Intlayer से किसी भी AI कॉल के बिना प्रक्रिया में शामिल रहने की आवश्यकता होती है:
+
+- `--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/hi/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/hi/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"
+```
+
+यह सत्र केवल उस प्रॉम्प्ट और कमांड आउटपुट को वहन करेगा, न कि आपकी पूरी बातचीत को। यही टोकन प्रत्येक पुल अनुरोध पर `intlayer fill` चलाने के लिए [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) में काम करता है।
+
+> `claude setup-token` द्वारा जारी टोकन केवल Claude Code को प्रमाणित करता है। इसका उपयोग `ai.apiKey` में Anthropic API कुंजी के रूप में नहीं किया जा सकता है। अनुवाद के लिए, `intlayer fill` आपके [Intlayer खाते](https://app.intlayer.org) (मुफ्त स्तर शामिल) या [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/configuration.md#ai-configuration) में कॉन्फ़िगर की गई आपकी अपनी प्रदाता कुंजी का उपयोग करता है।
+
+## सारांश
+
+| कार्य                              | कौन करता है              | एजेंट संदर्भ में टोकन    |
+| ---------------------------------- | ------------------------ | ------------------------ |
+| क्या स्थानीयकृत करना है यह तय करना | Claude Code              | कम                       |
+| स्ट्रिंग्स निकालना                 | `intlayer extract`       | कोई नहीं                 |
+| सामग्री का अनुवाद करना             | `intlayer fill`          | कोई नहीं                 |
+| प्रलेखन का अनुवाद करना             | `intlayer doc translate` | कोई नहीं                 |
+| प्रलेखन अद्यतन करना                | `intlayer doc review`    | कोई नहीं                 |
+| कमांड चलाना                        | हेडलेस Claude Code       | प्रॉम्प्ट + कमांड आउटपुट |

package/frequent_questions/id/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Cara membatasi konsumsi token Claude Code untuk menghasilkan terjemahan
+description: Mengapa menerjemahkan dengan Claude Code menghabiskan banyak token, apa yang dilakukan Intlayer sebagai gantinya (memfilter kunci yang diterjemahkan, memotong JSON, menerjemahkan markdown blok demi blok), dan cara menggunakan kembali langganan Claude Anda dengan claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - konsumsi token
+  - setup-token
+  - i18n
+  - internasionalisasi
+  - terjemahan
+  - fill
+  - mcp
+  - agen
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Cara membatasi konsumsi token Claude Code untuk menghasilkan terjemahan
+
+## Deskripsi Masalah
+
+Meminta Claude Code (atau agen pengodean apa pun) untuk menerjemahkan konten Anda adalah metode yang paling boros biaya. Untuk setiap eksekusi, agen harus:
+
+- Memuat seluruh file JSON atau file konten ke dalam konteksnya, bahkan kunci yang sudah diterjemahkan.
+- Mencari file terkait untuk memahami letak konten dan bagaimana strukturnya disusun.
+- Menentukan locale mana yang belum ada dan perlu dibuat.
+- Membaca ulang instruksi khusus Anda setiap saat ("ubah URL dengan cara ini", "biarkan nama merek dalam bahasa Inggris", "gunakan nada santai").
+- Menulis ulang seluruh file, termasuk bagian yang tidak mengalami perubahan.
+
+Semua itu dikirim ulang pada setiap giliran percakapan, sehingga biaya melonjak seiring `ukuran konten × jumlah locale × jumlah giliran`, dan setiap inkonsistensi format maupun kunci harus diperiksa secara manual.
+
+## Apa yang dilakukan Intlayer sebagai gantinya
+
+Kelebihan Intlayer adalah menjalankan pekerjaan tersebut di luar agen melalui alur kerja (pipeline) yang dirancang khusus untuk penerjemahan:
+
+- **Memfilter terjemahan yang sudah ada** untuk menekan penggunaan token. Kunci yang sudah diterjemahkan di dalam JSON Anda akan disaring, dan hanya kunci yang belum ada yang dikirim ke model.
+- **Menerjemahkan markdown blok demi blok.** Untuk dokumentasi, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-translate.md) dan [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-review.md) membandingkan setiap blok dengan dokumen dasar dan melewati blok yang sudah diterjemahkan atau tidak berubah.
+- **Memotong JSON (chunking)** jika ukurannya terlalu besar agar tetap berada di rentang konteks yang optimal.
+- **Meratakan dan menyusun ulang JSON** guna mengoptimalkan konsumsi token.
+- **Menyisipkan prompt khusus** untuk aturan tertentu terkait merek dan terminologi Anda (`applicationContext`, `--custom-instructions`), sehingga Anda hanya menuliskannya satu kali tanpa perlu mengulanginya di setiap percakapan.
+- **Memvalidasi struktur** untuk menjamin konsistensi dan mencegah pergeseran kunci, serta mempertahankan format (markdown, HTML, tag sisipan, bentuk jamak).
+- **Menerapkan manajemen percobaan ulang (retry)** apabila format output tidak valid.
+- **Mengantrekan dan memparalelkan permintaan** lintas file, potongan teks, dan locale untuk meningkatkan kecepatan.
+
+Semua proses ini tidak melewati konteks agen. Aturan praktisnya: biarkan agen memutuskan **apa** yang perlu diinternasionalisasi, dan biarkan Intlayer menangani pekerjaan berulang tersebut.
+
+## Solusi
+
+### 1. Delegasikan ekstraksi ke `intlayer extract`
+
+Alih-alih meminta agen menulis ulang setiap komponen secara manual, biarkan agen menjalankan perintah [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/extract.md). Perintah ini memindahkan string statis ke dalam file `.content` di samping komponen tanpa memuat seluruh file ke dalam konteks agen.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegasikan penerjemahan ke `intlayer fill`
+
+Jangan pernah meminta agen untuk menerjemahkan secara langsung. Perintah [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/fill.md) menerapkan alur kerja di atas: hanya mengirimkan kunci yang belum diterjemahkan, membaginya ke dalam beberapa potongan, memproses locale secara paralel, dan menuliskan hasilnya kembali ke file konten Anda.
+
+```bash
+npx intlayer fill
+```
+
+Beberapa opsi flag membantu mempersempit ruang lingkup eksekusi:
+
+- `--git-diff` (atau `--uncommitted`) hanya memproses kamus yang dimodifikasi pada branch saat ini.
+- `--file` atau `--keys` menargetkan file konten tertentu.
+- `--output-locales fr es` membatasi eksekusi hanya untuk locale yang benar-benar Anda butuhkan saat ini.
+- `--skip-metadata` melewati pembuatan judul, deskripsi, dan tag.
+- `--data-serialization toon` mengirimkan payload yang lebih ringkas ke model (mengurangi token, hasil sedikit kurang konsisten).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Terjemahkan markdown dengan `doc translate` dan `doc review`
+
+Meminta agen menerjemahkan file `.md` berarti menempelkan seluruh dokumen, untuk setiap locale, pada setiap perubahan. Sebaliknya, perintah [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-translate.md) dan [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-review.md) bekerja blok demi blok.
+
+Gunakan `doc translate` ketika file hasil terjemahan belum ada. Perintah ini memotong markdown, menerjemahkannya secara paralel, dan menulis file tujuan:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Gunakan `doc review` ketika file terjemahan sudah ada. Perintah ini membandingkan setiap blok dengan dokumen dasar, melewati blok yang sudah diterjemahkan atau tidak berubah, dan hanya mengirimkan blok yang berbeda:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Kedua perintah ini menerima aturan Anda satu kali saja, sehingga Anda tidak perlu mengulanginya di setiap prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dua mode pada `doc review` sangat berguna saat agen tetap harus dilibatkan tanpa memicu panggilan AI dari Intlayer:
+
+- `--mode report` mencatat blok-blok yang memerlukan penyesuaian lengkap dengan nomor baris, sehingga agen hanya mengubah blok tersebut.
+- `--mode synthesis` hanya melaporkan dokumen mana yang sudah diperbarui dan dokumen mana yang masih memiliki blok untuk diedit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Biarkan agen memanggil CLI melalui server MCP
+
+Dengan [server MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/mcp_server.md), agen menjawab berdasarkan dokumentasi terbaru dan menjalankan `intlayer fill` atau `intlayer doc review` secara langsung alih-alih mengimplementasikan kembali logika tersebut di dalam percakapan.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Memasang [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/agent_skills.md) melalui `npx intlayer init skills` juga mencegah agen menebak-nebak API Intlayer dan membaca ulang dokumentasi di setiap tugas.
+
+### 5. Gunakan kembali langganan Claude Anda dengan `claude setup-token`
+
+Menjalankan penyiapan i18n di dalam sesi Claude Code interaktif akan menumpuk seluruh riwayat percakapan dalam konteks. Alihkan tugas berat tersebut ke sesi headless yang singkat.
+
+Buat token berdurasi panjang dari langganan Claude Anda:
+
+```bash
+claude setup-token
+```
+
+Simpan token ini sebagai `CLAUDE_CODE_OAUTH_TOKEN` (di dalam file `.env` atau secret CI Anda), lalu gunakan kembali untuk sesi sekali jalan yang mengeksekusi perintah Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Sesi tersebut hanya memuat prompt dan output perintah tanpa menyertakan riwayat percakapan sebelumnya. Token yang sama juga berfungsi pada [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) untuk menjalankan `intlayer fill` di setiap pull request.
+
+> Token yang dibuat oleh `claude setup-token` hanya mengautentikasi Claude Code. Token ini tidak dapat digunakan sebagai kunci API Anthropic di `ai.apiKey`. Untuk proses penerjemahannya sendiri, `intlayer fill` menggunakan [akun Intlayer](https://app.intlayer.org) Anda (termasuk paket gratis) atau kunci penyedia Anda sendiri yang dikonfigurasi pada [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md#ai-configuration).
+
+## Ringkasan
+
+| Tugas                                 | Pelaksana                | Token dalam konteks agen |
+| ------------------------------------- | ------------------------ | ------------------------ |
+| Menentukan apa yang akan dilokalisasi | Claude Code              | Rendah                   |
+| Mengekstrak string                    | `intlayer extract`       | Tidak ada                |
+| Menerjemahkan konten                  | `intlayer fill`          | Tidak ada                |
+| Menerjemahkan dokumentasi             | `intlayer doc translate` | Tidak ada                |
+| Memperbarui dokumentasi               | `intlayer doc review`    | Tidak ada                |
+| Menjalankan perintah                  | Headless Claude Code     | Prompt + output perintah |