Como limitar o consumo de tokens do Claude Code para gerar traduções

Descrição do problema

Pedir ao Claude Code (ou a qualquer agente de programação) para traduzir seu conteúdo é a forma mais cara de realizá-lo. Em cada execução, o agente precisa:

• Carregar todo o arquivo JSON ou de conteúdo no seu contexto, até mesmo as chaves já traduzidas.
• Buscar nos arquivos relacionados para identificar onde o conteúdo reside e como está estruturado.
• Descobrir quais locales estão ausentes e precisam ser gerados.
• Reler suas instruções personalizadas a cada execução ("transformar URLs desta maneira", "manter o nome da marca em inglês", "usar forma informal").
• Reescrever todo o arquivo, inclusive as partes que não foram alteradas.

Tudo isso é reenviado a cada interação, fazendo com que o custo cresça conforme tamanho do conteúdo × número de locales × número de turnos, e qualquer divergência de formatação ou de chaves precise ser corrigida manualmente.

O que o Intlayer faz em vez disso

O diferencial do Intlayer é realizar esse trabalho fora do agente, através de um pipeline construído especificamente para tradução:

• Filtra traduções existentes para limitar o uso de tokens. As chaves já traduzidas no seu JSON são ignoradas, enviando apenas as pendentes ao modelo.
• Traduz markdown bloco a bloco. Para a documentação, doc translate e doc review comparam cada bloco com o documento base e ignoram blocos já traduzidos ou inalterados.
• Divide o seu JSON em partes (chunking) se for muito grande, garantindo operação na melhor faixa da janela de contexto.
• Achata e reconstrói o seu JSON para otimizar o consumo de tokens.
• Insere prompts personalizados para regras específicas da sua marca e terminologia (applicationContext, --custom-instructions), permitindo que você as defina uma única vez em vez de repeti-las em cada conversa.
• Valida a estrutura para assegurar consistência e evitar desvio de chaves, preservando a formatação (markdown, HTML, inserções, plurais).
• Implementa gestão de novas tentativas (retry) caso a saída apresente formato inválido.
• Enfileira e paraleliza requisições entre arquivos, blocos e locales para aumentar a velocidade.

Nada disso transita pelo contexto do agente. A regra prática: deixe o agente decidir o que internacionalizar, e deixe o Intlayer cuidar do trabalho repetitivo.

Solução

1. Delegar a extração para intlayer extract

Em vez de pedir ao agente para reescrever cada componente manualmente, deixe-o executar o comando extract. Ele move strings fixas para um arquivo .content ao lado do componente sem carregar o arquivo completo no contexto do agente.

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

2. Delegar a tradução para intlayer fill

Nunca peça ao agente para traduzir. O comando fill aplica o pipeline acima: envia apenas as chaves ausentes, as fragmenta, processa os locales em paralelo e grava o resultado de volta nos seus arquivos de conteúdo.

npx intlayer fill

Algumas flags mantêm a execução enxuta:

• --git-diff (ou --uncommitted) processa apenas os dicionários alterados no branch atual.
• --file ou --keys foca em arquivos de conteúdo específicos.
• --output-locales fr es restringe a execução aos locales realmente necessários no momento.
• --skip-metadata ignora a criação de título, descrição e tags.
• --data-serialization toon envia uma carga útil mais compacta para o modelo (menos tokens, saída ligeiramente menos previsível).

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

3. Traduzir markdown com doc translate e doc review

Pedir a um agente para traduzir um arquivo .md significa colar todo o documento, para cada locale, a cada alteração. Os comandos doc translate e doc review operam bloco a bloco.

Use doc translate quando o arquivo traduzido ainda não existir. Ele divide o markdown, traduz em paralelo e grava os arquivos de destino:

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

Use doc review quando o arquivo traduzido já existir. Ele compara cada bloco com o documento base, ignora os blocos já traduzidos ou inalterados e envia apenas os divergentes:

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

Ambos os comandos aceitam suas regras uma única vez, sem a necessidade de repeti-las em cada prompt:

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

Dois modos de doc review são úteis quando o agente precisa continuar no fluxo sem disparar chamadas de IA pelo Intlayer:

• --mode report lista os blocos que exigem atenção com números de linha, permitindo que o agente edite apenas esses blocos.
• --mode synthesis reporta apenas quais documentos estão em dia e quais contêm blocos pendentes de edição.

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

4. Permitir que o agente chame a CLI através do servidor MCP

Com o servidor MCP do Intlayer, o agente responde com base na documentação atualizada e executa intlayer fill ou intlayer doc review por conta própria em vez de reimplementar a lógica na conversa.

claude mcp add intlayer npx -y @intlayer/mcp

Instalar as Agent Skills com npx intlayer init skills também evita que o agente tente adivinhar a API do Intlayer e releia a documentação em cada tarefa.

5. Reutilizar sua assinatura do Claude com claude setup-token

Executar a configuração de i18n na sua sessão interativa do Claude Code mantém todo o histórico da conversa no contexto. Transfira esse trabalho pesado para uma sessão curta em modo headless.

Gere um token de longa duração a partir da sua assinatura do Claude:

claude setup-token

Armazene-o como CLAUDE_CODE_OAUTH_TOKEN (em um arquivo .env ou nas variáveis secretas do seu CI) e reutilize-o para uma sessão pontual que execute os comandos do Intlayer:

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

A sessão carregará apenas esse prompt e a saída do comando, sem o histórico da sua conversa. O mesmo token funciona na Claude Code GitHub Action para rodar intlayer fill em cada pull request.

O token gerado por claude setup-token autentica somente o Claude Code. Ele não pode ser usado como chave de API da Anthropic em ai.apiKey. Para a tradução em si, intlayer fill usa a sua conta do Intlayer (plano gratuito incluso) ou a sua chave própria configurada em ai.

Resumo