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 y doc review 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. Este traslada las cadenas fijas a un archivo .content junto al componente sin cargar todo el archivo en el contexto del agente.

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 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.

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).

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 y doc review 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:

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:

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:

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.

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, 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.

claude mcp add intlayer npx -y @intlayer/mcp

Instalar las Agent Skills 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:

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:

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 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 (plan gratuito incluido) o tu propia clave de proveedor configurada en ai.

Resumen