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 and doc review 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 command. It moves hard-coded strings into a .content file next to the component without loading the whole file into the agent's context.

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

2. Delegate translation to intlayer fill

Never ask the agent to translate. The fill 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.

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

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

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:

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:

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.

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

4. Let the agent call the CLI through the MCP server

With the Intlayer MCP server, the agent answers from the current documentation and runs intlayer fill or intlayer doc review itself instead of re-implementing it in the conversation.

claude mcp add intlayer npx -y @intlayer/mcp

Installing the Agent Skills 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:

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:

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 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 (free tier included) or your own provider key configured in ai.

Summary