如何限制 Claude Code 生成翻译时的 Token 消耗

    问题描述

    让 Claude Code（或任何编码 Agent）直接翻译内容是最昂贵的做法。每次执行时，Agent 都必须：

    • 将整个 JSON 或内容文件加载到上下文中，甚至包括已经翻译过的键。
    • 检索相关文件以确定内容的存放位置和结构。
    • 分析缺少哪些语言环境（Locales）并需要生成。
    • 每次都要重新阅读您的自定义指令（“按此规则转换 URL”，“保留英文品牌名称”，“使用非正式语气”等）。
    • 重写整个文件，包括未发生变动的部分。

    所有这些内容在每次对话轮次中都会被重新发送，导致成本随着 内容大小 × 语言环境数量 × 对话轮次 呈倍数增长，而且格式或键名出现的任何偏差都必须手动排查。

    Intlayer 采取的替代方案

    Intlayer 的优势在于将这些工作移至 Agent 之外，通过专为翻译构建的流水线来完成：

    • 过滤已存在的翻译以限制 Token 消耗。JSON 中已翻译的键会被剥离，仅将缺失的键发送给模型。
    • 逐块翻译 Markdown。 对于文档，doc translate 与 doc review 会将每个文本块与基础文档进行比对，直接跳过已翻译或未更改的块。
    • 超大 JSON 自动分块（Chunking），使其始终处于上下文窗口的最佳处理区间内。
    • 扁平化与重构 JSON 以优化 Token 消耗。
    • 插入自定义 Prompt 以适配品牌与术语规则（applicationContext, --custom-instructions），只需编写一次，无需在每次对话中反复传递。
    • 校验数据结构以确保一致性并防止键名漂移，同时完整保留原始排版格式（Markdown、HTML、插值、复数等）。
    • 内置重试机制以应对输出格式错误。
    • 请求排队与并行处理跨文件、分块和语言环境，显著提高翻译速度。

    所有这些工作都不会占用 Agent 的上下文。黄金法则是：让 Agent 决定需要国际化什么，而让 Intlayer 处理繁重的重复性流水线。

    解决方案

    1. 将提取工作委托给 intlayer extract

    无需让 Agent 手动重写每个组件，直接运行 extract 命令即可。它会将硬编码字符串提取到组件同目录下的 .content 文件中，而不会将完整文件加载到 Agent 上下文中。

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

    2. 将翻译工作委托给 intlayer fill

    切勿让 Agent 直接进行翻译。fill 命令会自动应用上述流水线：只发送缺失的键、进行分块、并行处理各个语言环境，并将结果写回内容文件中。

    bash
    npx intlayer fill

    通过几个参数可以精简执行范围：

    • --git-diff（或 --uncommitted）仅处理当前分支中发生更改的字典。
    • --file 或 --keys 针对特定的内容文件。
    • --output-locales fr es 仅限制在当前实际需要的语言环境中。
    • --skip-metadata 跳过标题、描述和标签的生成。
    • --data-serialization toon 向模型发送更紧凑的数据格式（更少的 Token，输出略微不可控）。
    bash
    npx intlayer fill --git-diff --output-locales fr es --skip-metadata

    3. 使用 doc translate 与 doc review 翻译 Markdown

    让 Agent 翻译 .md 文件意味着每次修改都要在每个语言环境中粘贴整个文档。而 doc translate 和 doc review 命令则是按文本块逐步处理的。

    当目标翻译文件尚不存在时，使用 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."

    在需要 Agent 参与但无需 Intlayer 发起 AI 调用的场景下，doc review 的两种模式非常实用：

    • --mode report 输出需要关注的文本块及行号，让 Agent 仅修改这些特定块。
    • --mode synthesis 仅输出哪些文档是最新的，哪些文档仍有待编辑的块。
    bash
    npx intlayer doc review --mode report --locales fr

    4. 让 Agent 通过 MCP 服务调用 CLI

    借助 Intlayer MCP 服务，Agent 可以依据最新的文档回答，并自行执行 intlayer fill 或 intlayer doc review，而无需在对话中重新实现这些逻辑。

    bash
    claude mcp add intlayer npx -y @intlayer/mcp

    通过 npx intlayer init skills 安装 Agent Skills，还可以避免 Agent 盲目猜测 Intlayer API 或在每个任务中重复阅读文档。

    5. 通过 claude setup-token 复用 Claude 订阅

    在交互式 Claude Code 会话中运行国际化设置会将整个对话历史保留在上下文中。将繁重的工作移至简短的无头（Headless）会话中执行：

    从 Claude 订阅中生成长效 Token：

    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"

    该会话仅包含该 Prompt 和命令输出，无需携带冗长的对话上下文。同一个 Token 也可以在 Claude Code GitHub Action 中使用，从而在每次 Pull Request 时运行 intlayer fill。

    通过 claude setup-token 颁发的 Token 仅用于 Claude Code 认证。它不能在 ai.apiKey 中作为 Anthropic API Key 使用。对于翻译本身，intlayer fill 会使用您的 Intlayer 账户（包含免费额度）或在 ai 中配置的专属模型 Key。

    总结

    任务执行者Agent 上下文中的 Token 消耗
    决定要本地化的内容Claude Code低
    提取文本字符串intlayer extract无
    翻译声明内容intlayer fill无
    翻译 Markdown 文档intlayer doc translate无
    更新 Markdown 文档intlayer doc review无
    批量执行命令Headless Claude Code仅 Prompt + 命令输出