拓冰网站定制 
1. 为什么要把 claude-code-guide 文档翻译流程搬到统一通道claude-code-guide 这个项目本身是一份围绕 Claude 代码工具的使用指南英文原仓库里塞满了安装命令、环境变量、MCP 配置、子智能体提示词、故障排查这些内容。它的章节结构其实很清晰入门指南、配置与环境、命令与用法、界面与输入、高级功能、安全与权限、自动化与集成、帮助与故障排除、第三方集成。问题在于这份文档的更新频率不低英文原仓库一有改动中文版就得跟着动。如果每次靠人工逐段翻译术语会飘、章节会错位、代码块里的注释也容易被顺手翻掉最后产出的中文版和原仓库结构对不上读者按目录找内容时就会迷路。我试过用最原始的方式处理把英文 Markdown 拉下来丢进翻译工具再手工贴回去。结果就是settings.json里的字段名被翻译了ANTHROPIC_API_KEY变成了「人类学接口密钥」这种离谱东西代码块里的claude config set -g theme dark也被改得面目全非。更麻烦的是原仓库的目录层级和锚点链接一旦被破坏中文版就失去了「结构对齐」这个最重要的价值。所以这套流程的核心目标不是「把英文变中文」而是三件事第一从原仓库稳定拉取英文文档保留原始目录结构第二建立术语表和替换规则让MCP、子智能体、环境变量这类词在全文中保持一致第三把批量翻译请求的 endpoint 统一改到 TaoToken 的 API 通道用同一个 Key 完成翻译和校对避免在多个平台之间来回切换。TaoToken 在这里扮演的是「统一 Key/API 通道」的角色官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 不带 UTM 参数。适合谁跟做如果你正在维护一个中文技术文档仓库或者你负责把某个英文工具指南本地化又或者你只是想用脚本把一批 Markdown 批量翻译成中文并保持术语一致这套流程都能直接套用。它不依赖特定的编辑器核心就是「拉取 → 术语表 → 批量翻译 → 逐段校验 → 回写」这条链路。这里要提前说清楚一个边界TaoToken 是 API 通道不是编辑器也不是文档托管平台。翻译请求发出去、结果拿回来最终写回文件、提交 Git 这些动作还是在你本地完成。把 endpoint 改到 TaoToken只是让翻译请求走一个统一的入口方便管理 Key 和模型选择。2. TaoToken 前置准备Key、模型与 claude-code-guide 翻译场景的对接在开始写翻译脚本之前需要先把 TaoToken 这边的准备工作做完。这一步不复杂但顺序不能乱否则后面脚本跑起来会一直报 401。首先是拿 Key。进入 TaoToken 控制台创建一个 API Key。这个 Key 后面会用在两个地方一是翻译脚本里的Authorization请求头二是如果你用 Claude Code 本身来辅助校对也需要把它写进环境变量。控制台地址是 https://taotoken.net/console API Keys 管理页是 https://taotoken.net/api-keys 。创建的时候建议给 Key 起一个能认出来的名字比如doc-translate方便以后轮换。拿到 Key 之后确认你要用的模型 ID。翻译文档这种任务对模型的要求是「长文本稳定、术语遵循好、输出格式不乱」。你可以先在模型对话页面里试一段 claude-code-guide 的英文原文看看输出质量。模型对话入口是 https://taotoken.net/models 这个页面可以直接粘贴一段英文文档观察它是否会把代码块原样保留、是否会把MCP翻译成中文。如果试下来满意就把对应的模型 ID 记下来后面写进脚本的model字段。接下来是 Base URL。TaoToken 的 API 地址是 https://taotoken.net/api 注意这里不加任何 UTM 参数。在脚本里请求的完整路径通常是https://taotoken.net/api/v1/messages或者兼容 OpenAI 格式的https://taotoken.net/api/v1/chat/completions具体取决于你用的 SDK。如果你用的是 Anthropic 风格的调用就把base_url设成https://taotoken.net/apiSDK 会自动拼接后面的路径。这里有一个容易踩的坑很多人会把 Key 直接写进脚本文件然后提交到 Git。千万不要这么做。正确的做法是把 Key 放进环境变量脚本里用os.environ.get(TAOTOKEN_API_KEY)读取。如果你在本地跑可以写一个.env文件然后把它加进.gitignore。如果你用 Claude Code 来辅助校对环境变量的名字建议用ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这样 Claude Code 启动时会自动读取。关于模型选择翻译和校对可以用同一个模型也可以分开。翻译阶段用输出稳定的模型校对阶段用更擅长发现术语不一致的模型。如果你打算长期做这件事可以考虑 Coding Plan它更适合持续性的编码和 Agent 类任务入口是 https://taotoken.net/coding-plan 。不过对于单纯的文档翻译按量调用 API 就够了不必一开始就上套餐。还有一个细节claude-code-guide 的原文里有大量代码块和配置片段这些内容在翻译时必须原样保留。所以在准备阶段最好先确认你的翻译脚本有没有「保护代码块」的逻辑。如果没有后面术语替换规则里要专门处理。3. 可复制配置目录映射、术语表与翻译脚本的 settings 片段这一节是整套流程的核心所有配置都可以直接复制修改。先讲目录映射再讲术语表最后给出翻译脚本的配置片段。目录映射的目的是让中文版和英文原仓库的结构一一对应。假设你把英文原仓库克隆到了./claude-code-guide-en中文版输出到./claude-code-guide-zh。原仓库的目录结构大致是这样的claude-code-guide-en/ ├── README.md ├── docs/ │ ├── getting-started.md │ ├── configuration.md │ ├── commands.md │ ├── interface.md │ ├── advanced/ │ │ ├── subagents.md │ │ └── mcp.md │ ├── security.md │ ├── automation.md │ └── troubleshooting.md └── integrations/ └── deepseek.md对应的中文版目录保持同样的层级只把文件名保留英文内容翻译成中文。这样做的好处是锚点链接不会断Git diff 也容易对比。你可以写一个mapping.json来显式声明映射关系{ source_root: ./claude-code-guide-en, target_root: ./claude-code-guide-zh, file_map: { README.md: README.md, docs/getting-started.md: docs/getting-started.md, docs/configuration.md: docs/configuration.md, docs/commands.md: docs/commands.md, docs/interface.md: docs/interface.md, docs/advanced/subagents.md: docs/advanced/subagents.md, docs/advanced/mcp.md: docs/advanced/mcp.md, docs/security.md: docs/security.md, docs/automation.md: docs/automation.md, docs/troubleshooting.md: docs/troubleshooting.md, integrations/deepseek.md: integrations/deepseek.md }, skip_patterns: [*.png, *.jpg, *.gif, *.svg], preserve_blocks: [code, pre, table] }skip_patterns用来跳过图片资源preserve_blocks声明哪些块在翻译时要原样保留。代码块和表格是最容易出问题的表格里的英文表头如果被翻译了列对齐就会乱。接下来是术语表。术语表的作用是强制统一翻译避免同一个词在不同章节出现不同译法。把下面这段存成glossary.json{ MCP: MCP, Model Context Protocol: 模型上下文协议MCP, subagent: 子智能体, subagents: 子智能体, environment variable: 环境变量, API key: API 密钥, settings.json: settings.json, CLAUDE.md: CLAUDE.md, slash command: 斜杠命令, keyboard shortcut: 键盘快捷键, troubleshooting: 故障排除, getting started: 入门指南, configuration: 配置与环境, commands: 命令与用法, interface: 界面与输入, advanced: 高级功能, security: 安全与权限, automation: 自动化与集成, permission mode: 权限模式, thinking keyword: 思考关键词, token: 令牌, prompt: 提示词, agent: 智能体, workflow: 工作流, repository: 代码仓库, pull request: 拉取请求PR, diff: 差异补丁, scope: 作用域, stdio: stdio, SSE: SSE, HTTP: HTTP }注意MCP、settings.json、CLAUDE.md、stdio、SSE、HTTP这些词在术语表里是「原文映射到原文」意思是翻译时不要动它们。Model Context Protocol这种全称第一次出现时给出中文加英文缩写后面统一用MCP。然后是翻译脚本的配置片段。下面这段是translate_config.json它把 TaoToken 的 endpoint、模型、术语表路径、目录映射都串起来{ api: { base_url: https://taotoken.net/api, endpoint: /v1/messages, api_key_env: TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, max_tokens: 8192, temperature: 0.2 }, paths: { mapping: ./mapping.json, glossary: ./glossary.json, cache_dir: ./.translate-cache, log_dir: ./.translate-logs }, translation: { chunk_size: 3000, chunk_overlap: 200, preserve_code_blocks: true, preserve_tables: true, preserve_links: true, glossary_strict: true }, review: { enabled: true, model: claude-sonnet-4-20250514, check_terms: true, check_structure: true, check_code_blocks: true } }temperature设成 0.2 是为了让输出更稳定翻译任务不需要创造性。chunk_size设成 3000 字符左右是因为太长的段落一次翻译容易丢内容太短又会破坏上下文。chunk_overlap留 200 字符是为了让相邻块之间有重叠避免句子被切断。如果你用 Claude Code 本身来跑翻译可以在项目根目录放一个.claude/settings.json把环境变量写进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意这里的ANTHROPIC_API_KEY要换成你自己的 Key而且这个文件不要提交到公开仓库。如果你用 Cline 或者 CC Switch 这类工具配置逻辑是一样的Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你选定的模型。这三件套缺一不可只填 Base URL 不填 Key 会报 401只填 Key 不填 Model ID 可能会走到默认模型上。4. 验证请求从单文件翻译到全量批处理的成功结果配置写完之后不要一上来就跑全量。先用一个文件验证请求能不能通再逐步放大。第一步验证 API 连通性。写一个最小的 Python 脚本只翻译一句话import os import json import urllib.request api_key os.environ.get(TAOTOKEN_API_KEY) base_url https://taotoken.net/api endpoint /v1/messages payload { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ { role: user, content: Translate the following into Chinese, keep MCP unchanged: MCP extends Claude with external tools. } ] } req urllib.request.Request( base_url endpoint, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, x-api-key: api_key, anthropic-version: 2023-06-01 }, methodPOST ) with urllib.request.urlopen(req, timeout60) as resp: result json.loads(resp.read().decode(utf-8)) print(result[content][0][text])跑通之后你应该看到类似「MCP 通过外部工具扩展 Claude 的能力。」这样的输出而且MCP没有被翻译。如果这里报 401说明 Key 没读到或者 Key 无效如果报local proxy failed说明你的网络环境有问题需要检查本地的网络配置如果报reading choices之类的错误通常是响应格式和你的解析代码不匹配先打印原始响应看看结构。第二步单文件翻译。拿docs/getting-started.md做测试。脚本的逻辑是读取英文原文按段落切块对每个块调用翻译接口把结果拼回去最后写入中文版对应路径。切块的时候要跳过代码块和表格这两类内容直接原样复制。import re def split_markdown(text, chunk_size3000, overlap200): lines text.split(\n) chunks [] current [] current_len 0 in_code False for line in lines: if line.strip().startswith(): in_code not in_code current.append(line) current_len len(line) if current_len chunk_size and not in_code: chunks.append(\n.join(current)) current current[-3:] if overlap else [] current_len sum(len(l) for l in current) if current: chunks.append(\n.join(current)) return chunks这个切块函数会在代码块内部不切分避免把一段配置命令切成两半。翻译每个块的时候把术语表作为系统提示的一部分传进去def build_prompt(chunk, glossary): terms \n.join([f- {k} {v} for k, v in glossary.items()]) return f你是一名技术文档翻译。请把下面的英文 Markdown 翻译成中文。 规则 1. 代码块、行内代码、URL、文件路径原样保留不要翻译。 2. 表格结构保留表头可以翻译但列对齐不能乱。 3. 以下术语必须按映射处理 {terms} 4. 只输出翻译后的 Markdown不要加任何解释。 原文 {chunk} 第三步全量批处理。把mapping.json里的每个文件都跑一遍结果写入claude-code-guide-zh对应路径。跑的时候建议加一个缓存每个块的翻译结果按内容哈希存到.translate-cache这样重跑时不会重复调用接口。全量跑完之后你会得到一份结构对齐的中文版目录层级和英文原仓库完全一致。成功的结果是什么样的打开claude-code-guide-zh/docs/commands.md你应该看到命令表格里的claude config set -g theme dark原样保留而表格上方的说明文字已经变成中文。打开docs/advanced/mcp.mdMCP这个词全文统一没有出现「模型上下文协议」和「MCP」混用的情况。打开docs/configuration.md环境变量名ANTHROPIC_API_KEY没有被翻译但旁边的注释变成了中文。如果这些都对上了说明翻译链路是通的。接下来就是校对阶段把机器翻译的痕迹磨掉。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth翻译流程跑起来之后最容易卡住的地方其实不是翻译质量而是请求层面的报错。下面这几个是我在实际操作中遇到过的按报错原文对照排查。第一个401 Unauthorized。这个报错的意思是 Key 没被正确识别。常见原因有三个一是环境变量名写错了比如脚本里读的是TAOTOKEN_API_KEY但你实际导出的是TAOTOKEN_KEY二是 Key 前面多了空格或者引号比如export TAOTOKEN_API_KEY sk-xxx那个空格会被带进请求头三是请求头字段名不对Anthropic 风格用x-api-keyOpenAI 风格用Authorization: Bearer两者不能混。排查方法很简单在脚本里打印一下api_key[:8]和api_key[-4:]确认 Key 被正确读取再检查请求头字段名和你的 endpoint 是否匹配。第二个local proxy failed。这个报错通常出现在你本地有网络中间层的情况下。它不是说 TaoToken 不可用而是你的请求在到达 TaoToken 之前就被本地环境拦住了。排查顺序是先确认你的终端能不能直接访问https://taotoken.net/api再检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置。如果你之前为了别的用途设过这些变量它们会干扰请求。临时清掉再试unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY然后重新跑一次单文件翻译。如果清掉之后能通说明就是本地网络配置的问题不是 Key 或 endpoint 的问题。第三个reading choices 相关报错。这个通常出现在你用的 SDK 期望 OpenAI 格式的响应但实际拿到的是 Anthropic 格式或者反过来。比如你用 OpenAI 的 Python SDK把base_url设成https://taotoken.net/api但请求路径拼成了/v1/chat/completions而 TaoToken 在这个路径下返回的结构和 SDK 期望的不一致解析choices字段时就会报错。解决办法是确认你的 SDK 和 endpoint 匹配用 Anthropic SDK 就走/v1/messages用 OpenAI SDK 就走/v1/chat/completions不要交叉。如果你不确定先用curl手动发一个请求看返回的 JSON 顶层字段是content还是choices。curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:ping}]} | head -c 500第四个OAuth 相关报错。如果你用 Claude Code 的/mcp命令连接远程 MCP 服务可能会遇到 OAuth 认证失败。这个和翻译流程本身关系不大但如果你在翻译过程中顺手配置了 MCP就会碰到。排查方法是先确认 MCP 服务的 URL 和认证头是否正确再用claude mcp list看服务有没有被正确加载。如果报的是OAuth相关错误检查你的--header参数里Authorization的值有没有带Bearer前缀有些服务要求带有些不要求。除了请求层面的报错翻译质量层面也有几个高频问题。一是代码块被翻译表现为npm install -g anthropic-ai/claude-code变成了中文注释混排。这个要在切块阶段就跳过代码块或者在提示词里强调「代码块原样保留」。二是术语不一致比如同一篇文档里subagent一会儿译成「子智能体」一会儿译成「子代理」。这个靠术语表强制约束glossary_strict设为true时脚本会在翻译后做一次术语检查发现不一致就重新翻译那个块。三是表格错位表现为中文表头和英文内容对不齐。这个在翻译后要做一次表格结构校验确认列数没变。如果你在排查过程中需要对照接口文档接入文档入口是 https://taotoken.net/doc API Keys 管理入口是 https://taotoken.net/api-keys 。这两个页面在排查 401 和 endpoint 问题时最常用。6. 把翻译请求固定到 TaoToken长期维护与语义一致的收尾动作整套流程跑通之后最后一步是把它固定下来让后续的文档更新可以重复执行。这里的关键不是「一次性翻译完」而是「原仓库更新时中文版能低成本跟进」。具体做法是写一个sync.sh把拉取、翻译、校对、提交串起来#!/usr/bin/env bash set -euo pipefail EN_DIR./claude-code-guide-en ZH_DIR./claude-code-guide-zh # 1. 拉取英文原仓库最新内容 if [ -d $EN_DIR/.git ]; then git -C $EN_DIR pull --ff-only else git clone https://github.com/your-org/claude-code-guide.git $EN_DIR fi # 2. 对比文件哈希只翻译有变化的文件 python3 scripts/diff_files.py --mapping mapping.json --cache .translate-cache # 3. 批量翻译 python3 scripts/translate.py --config translate_config.json # 4. 校对术语一致性 结构对齐 代码块完整性 python3 scripts/review.py --config translate_config.json # 5. 输出报告 python3 scripts/report.py --output .translate-logs/report.mddiff_files.py的作用是计算每个英文文件的哈希和缓存里的哈希对比只把变化的文件交给翻译脚本。这样原仓库改了一个章节你只需要重新翻译那一个文件不用全量重跑。review.py做三件事扫描中文版全文检查术语表里的每个词是否按映射出现对比中英文版的标题层级确认 H2/H3 数量一致检查代码块数量是否一致防止翻译过程中代码块被吞掉。校对阶段可以用模型对话页面来辅助。把中文版的一个章节贴进去让模型检查「有没有术语不一致的地方」入口是 https://taotoken.net/models 。这个页面适合做抽样检查不适合全量跑因为全量校对还是脚本更高效。如果你打算长期维护这个中文版建议把翻译脚本和术语表都放进版本控制但 Key 和.env不要提交。术语表可以随着翻译过程不断补充比如你发现permission mode在原文里有两种译法就把它加进glossary.json下次翻译就会自动统一。目录映射也可以扩展原仓库新增了文件就在mapping.json里加一条。最后说一个实际经验翻译技术文档时最耗时的不是翻译本身而是校对。机器翻译出来的内容术语对了、结构对了但读起来还是有「翻译腔」。我的做法是第一遍用脚本全量翻译第二遍用模型对话页面逐章润色第三遍人工只读一遍专门看代码块和配置片段有没有被误伤。这三遍下来中文版的可读性会明显好于一次性翻译。如果你在长期维护过程中需要更稳定的调用额度可以了解一下 Coding Plan入口是 https://taotoken.net/coding-plan 。它更适合持续性的编码和 Agent 类任务文档翻译这种周期性任务按量调用 API 也完全够用。关键是无论你用哪种方式Base URL、Key、Model ID 这三件套保持一致翻译请求就始终走同一个通道不会因为换工具而重新配置一遍。 claude-code-guide 项目指南中文版：把文档翻译流程改到 TaoToken
1. 为什么要把 claude-code-guide 文档翻译流程搬到统一通道claude-code-guide 这个项目本身是一份围绕 Claude 代码工具的使用指南英文原仓库里塞满了安装命令、环境变量、MCP 配置、子智能体提示词、故障排查这些内容。它的章节结构其实很清晰入门指南、配置与环境、命令与用法、界面与输入、高级功能、安全与权限、自动化与集成、帮助与故障排除、第三方集成。问题在于这份文档的更新频率不低英文原仓库一有改动中文版就得跟着动。如果每次靠人工逐段翻译术语会飘、章节会错位、代码块里的注释也容易被顺手翻掉最后产出的中文版和原仓库结构对不上读者按目录找内容时就会迷路。我试过用最原始的方式处理把英文 Markdown 拉下来丢进翻译工具再手工贴回去。结果就是settings.json里的字段名被翻译了ANTHROPIC_API_KEY变成了「人类学接口密钥」这种离谱东西代码块里的claude config set -g theme dark也被改得面目全非。更麻烦的是原仓库的目录层级和锚点链接一旦被破坏中文版就失去了「结构对齐」这个最重要的价值。所以这套流程的核心目标不是「把英文变中文」而是三件事第一从原仓库稳定拉取英文文档保留原始目录结构第二建立术语表和替换规则让MCP、子智能体、环境变量这类词在全文中保持一致第三把批量翻译请求的 endpoint 统一改到 TaoToken 的 API 通道用同一个 Key 完成翻译和校对避免在多个平台之间来回切换。TaoToken 在这里扮演的是「统一 Key/API 通道」的角色官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 不带 UTM 参数。适合谁跟做如果你正在维护一个中文技术文档仓库或者你负责把某个英文工具指南本地化又或者你只是想用脚本把一批 Markdown 批量翻译成中文并保持术语一致这套流程都能直接套用。它不依赖特定的编辑器核心就是「拉取 → 术语表 → 批量翻译 → 逐段校验 → 回写」这条链路。这里要提前说清楚一个边界TaoToken 是 API 通道不是编辑器也不是文档托管平台。翻译请求发出去、结果拿回来最终写回文件、提交 Git 这些动作还是在你本地完成。把 endpoint 改到 TaoToken只是让翻译请求走一个统一的入口方便管理 Key 和模型选择。2. TaoToken 前置准备Key、模型与 claude-code-guide 翻译场景的对接在开始写翻译脚本之前需要先把 TaoToken 这边的准备工作做完。这一步不复杂但顺序不能乱否则后面脚本跑起来会一直报 401。首先是拿 Key。进入 TaoToken 控制台创建一个 API Key。这个 Key 后面会用在两个地方一是翻译脚本里的Authorization请求头二是如果你用 Claude Code 本身来辅助校对也需要把它写进环境变量。控制台地址是 https://taotoken.net/console API Keys 管理页是 https://taotoken.net/api-keys 。创建的时候建议给 Key 起一个能认出来的名字比如doc-translate方便以后轮换。拿到 Key 之后确认你要用的模型 ID。翻译文档这种任务对模型的要求是「长文本稳定、术语遵循好、输出格式不乱」。你可以先在模型对话页面里试一段 claude-code-guide 的英文原文看看输出质量。模型对话入口是 https://taotoken.net/models 这个页面可以直接粘贴一段英文文档观察它是否会把代码块原样保留、是否会把MCP翻译成中文。如果试下来满意就把对应的模型 ID 记下来后面写进脚本的model字段。接下来是 Base URL。TaoToken 的 API 地址是 https://taotoken.net/api 注意这里不加任何 UTM 参数。在脚本里请求的完整路径通常是https://taotoken.net/api/v1/messages或者兼容 OpenAI 格式的https://taotoken.net/api/v1/chat/completions具体取决于你用的 SDK。如果你用的是 Anthropic 风格的调用就把base_url设成https://taotoken.net/apiSDK 会自动拼接后面的路径。这里有一个容易踩的坑很多人会把 Key 直接写进脚本文件然后提交到 Git。千万不要这么做。正确的做法是把 Key 放进环境变量脚本里用os.environ.get(TAOTOKEN_API_KEY)读取。如果你在本地跑可以写一个.env文件然后把它加进.gitignore。如果你用 Claude Code 来辅助校对环境变量的名字建议用ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这样 Claude Code 启动时会自动读取。关于模型选择翻译和校对可以用同一个模型也可以分开。翻译阶段用输出稳定的模型校对阶段用更擅长发现术语不一致的模型。如果你打算长期做这件事可以考虑 Coding Plan它更适合持续性的编码和 Agent 类任务入口是 https://taotoken.net/coding-plan 。不过对于单纯的文档翻译按量调用 API 就够了不必一开始就上套餐。还有一个细节claude-code-guide 的原文里有大量代码块和配置片段这些内容在翻译时必须原样保留。所以在准备阶段最好先确认你的翻译脚本有没有「保护代码块」的逻辑。如果没有后面术语替换规则里要专门处理。3. 可复制配置目录映射、术语表与翻译脚本的 settings 片段这一节是整套流程的核心所有配置都可以直接复制修改。先讲目录映射再讲术语表最后给出翻译脚本的配置片段。目录映射的目的是让中文版和英文原仓库的结构一一对应。假设你把英文原仓库克隆到了./claude-code-guide-en中文版输出到./claude-code-guide-zh。原仓库的目录结构大致是这样的claude-code-guide-en/ ├── README.md ├── docs/ │ ├── getting-started.md │ ├── configuration.md │ ├── commands.md │ ├── interface.md │ ├── advanced/ │ │ ├── subagents.md │ │ └── mcp.md │ ├── security.md │ ├── automation.md │ └── troubleshooting.md └── integrations/ └── deepseek.md对应的中文版目录保持同样的层级只把文件名保留英文内容翻译成中文。这样做的好处是锚点链接不会断Git diff 也容易对比。你可以写一个mapping.json来显式声明映射关系{ source_root: ./claude-code-guide-en, target_root: ./claude-code-guide-zh, file_map: { README.md: README.md, docs/getting-started.md: docs/getting-started.md, docs/configuration.md: docs/configuration.md, docs/commands.md: docs/commands.md, docs/interface.md: docs/interface.md, docs/advanced/subagents.md: docs/advanced/subagents.md, docs/advanced/mcp.md: docs/advanced/mcp.md, docs/security.md: docs/security.md, docs/automation.md: docs/automation.md, docs/troubleshooting.md: docs/troubleshooting.md, integrations/deepseek.md: integrations/deepseek.md }, skip_patterns: [*.png, *.jpg, *.gif, *.svg], preserve_blocks: [code, pre, table] }skip_patterns用来跳过图片资源preserve_blocks声明哪些块在翻译时要原样保留。代码块和表格是最容易出问题的表格里的英文表头如果被翻译了列对齐就会乱。接下来是术语表。术语表的作用是强制统一翻译避免同一个词在不同章节出现不同译法。把下面这段存成glossary.json{ MCP: MCP, Model Context Protocol: 模型上下文协议MCP, subagent: 子智能体, subagents: 子智能体, environment variable: 环境变量, API key: API 密钥, settings.json: settings.json, CLAUDE.md: CLAUDE.md, slash command: 斜杠命令, keyboard shortcut: 键盘快捷键, troubleshooting: 故障排除, getting started: 入门指南, configuration: 配置与环境, commands: 命令与用法, interface: 界面与输入, advanced: 高级功能, security: 安全与权限, automation: 自动化与集成, permission mode: 权限模式, thinking keyword: 思考关键词, token: 令牌, prompt: 提示词, agent: 智能体, workflow: 工作流, repository: 代码仓库, pull request: 拉取请求PR, diff: 差异补丁, scope: 作用域, stdio: stdio, SSE: SSE, HTTP: HTTP }注意MCP、settings.json、CLAUDE.md、stdio、SSE、HTTP这些词在术语表里是「原文映射到原文」意思是翻译时不要动它们。Model Context Protocol这种全称第一次出现时给出中文加英文缩写后面统一用MCP。然后是翻译脚本的配置片段。下面这段是translate_config.json它把 TaoToken 的 endpoint、模型、术语表路径、目录映射都串起来{ api: { base_url: https://taotoken.net/api, endpoint: /v1/messages, api_key_env: TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, max_tokens: 8192, temperature: 0.2 }, paths: { mapping: ./mapping.json, glossary: ./glossary.json, cache_dir: ./.translate-cache, log_dir: ./.translate-logs }, translation: { chunk_size: 3000, chunk_overlap: 200, preserve_code_blocks: true, preserve_tables: true, preserve_links: true, glossary_strict: true }, review: { enabled: true, model: claude-sonnet-4-20250514, check_terms: true, check_structure: true, check_code_blocks: true } }temperature设成 0.2 是为了让输出更稳定翻译任务不需要创造性。chunk_size设成 3000 字符左右是因为太长的段落一次翻译容易丢内容太短又会破坏上下文。chunk_overlap留 200 字符是为了让相邻块之间有重叠避免句子被切断。如果你用 Claude Code 本身来跑翻译可以在项目根目录放一个.claude/settings.json把环境变量写进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意这里的ANTHROPIC_API_KEY要换成你自己的 Key而且这个文件不要提交到公开仓库。如果你用 Cline 或者 CC Switch 这类工具配置逻辑是一样的Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你选定的模型。这三件套缺一不可只填 Base URL 不填 Key 会报 401只填 Key 不填 Model ID 可能会走到默认模型上。4. 验证请求从单文件翻译到全量批处理的成功结果配置写完之后不要一上来就跑全量。先用一个文件验证请求能不能通再逐步放大。第一步验证 API 连通性。写一个最小的 Python 脚本只翻译一句话import os import json import urllib.request api_key os.environ.get(TAOTOKEN_API_KEY) base_url https://taotoken.net/api endpoint /v1/messages payload { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ { role: user, content: Translate the following into Chinese, keep MCP unchanged: MCP extends Claude with external tools. } ] } req urllib.request.Request( base_url endpoint, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, x-api-key: api_key, anthropic-version: 2023-06-01 }, methodPOST ) with urllib.request.urlopen(req, timeout60) as resp: result json.loads(resp.read().decode(utf-8)) print(result[content][0][text])跑通之后你应该看到类似「MCP 通过外部工具扩展 Claude 的能力。」这样的输出而且MCP没有被翻译。如果这里报 401说明 Key 没读到或者 Key 无效如果报local proxy failed说明你的网络环境有问题需要检查本地的网络配置如果报reading choices之类的错误通常是响应格式和你的解析代码不匹配先打印原始响应看看结构。第二步单文件翻译。拿docs/getting-started.md做测试。脚本的逻辑是读取英文原文按段落切块对每个块调用翻译接口把结果拼回去最后写入中文版对应路径。切块的时候要跳过代码块和表格这两类内容直接原样复制。import re def split_markdown(text, chunk_size3000, overlap200): lines text.split(\n) chunks [] current [] current_len 0 in_code False for line in lines: if line.strip().startswith(): in_code not in_code current.append(line) current_len len(line) if current_len chunk_size and not in_code: chunks.append(\n.join(current)) current current[-3:] if overlap else [] current_len sum(len(l) for l in current) if current: chunks.append(\n.join(current)) return chunks这个切块函数会在代码块内部不切分避免把一段配置命令切成两半。翻译每个块的时候把术语表作为系统提示的一部分传进去def build_prompt(chunk, glossary): terms \n.join([f- {k} {v} for k, v in glossary.items()]) return f你是一名技术文档翻译。请把下面的英文 Markdown 翻译成中文。 规则 1. 代码块、行内代码、URL、文件路径原样保留不要翻译。 2. 表格结构保留表头可以翻译但列对齐不能乱。 3. 以下术语必须按映射处理 {terms} 4. 只输出翻译后的 Markdown不要加任何解释。 原文 {chunk} 第三步全量批处理。把mapping.json里的每个文件都跑一遍结果写入claude-code-guide-zh对应路径。跑的时候建议加一个缓存每个块的翻译结果按内容哈希存到.translate-cache这样重跑时不会重复调用接口。全量跑完之后你会得到一份结构对齐的中文版目录层级和英文原仓库完全一致。成功的结果是什么样的打开claude-code-guide-zh/docs/commands.md你应该看到命令表格里的claude config set -g theme dark原样保留而表格上方的说明文字已经变成中文。打开docs/advanced/mcp.mdMCP这个词全文统一没有出现「模型上下文协议」和「MCP」混用的情况。打开docs/configuration.md环境变量名ANTHROPIC_API_KEY没有被翻译但旁边的注释变成了中文。如果这些都对上了说明翻译链路是通的。接下来就是校对阶段把机器翻译的痕迹磨掉。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth翻译流程跑起来之后最容易卡住的地方其实不是翻译质量而是请求层面的报错。下面这几个是我在实际操作中遇到过的按报错原文对照排查。第一个401 Unauthorized。这个报错的意思是 Key 没被正确识别。常见原因有三个一是环境变量名写错了比如脚本里读的是TAOTOKEN_API_KEY但你实际导出的是TAOTOKEN_KEY二是 Key 前面多了空格或者引号比如export TAOTOKEN_API_KEY sk-xxx那个空格会被带进请求头三是请求头字段名不对Anthropic 风格用x-api-keyOpenAI 风格用Authorization: Bearer两者不能混。排查方法很简单在脚本里打印一下api_key[:8]和api_key[-4:]确认 Key 被正确读取再检查请求头字段名和你的 endpoint 是否匹配。第二个local proxy failed。这个报错通常出现在你本地有网络中间层的情况下。它不是说 TaoToken 不可用而是你的请求在到达 TaoToken 之前就被本地环境拦住了。排查顺序是先确认你的终端能不能直接访问https://taotoken.net/api再检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置。如果你之前为了别的用途设过这些变量它们会干扰请求。临时清掉再试unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY然后重新跑一次单文件翻译。如果清掉之后能通说明就是本地网络配置的问题不是 Key 或 endpoint 的问题。第三个reading choices 相关报错。这个通常出现在你用的 SDK 期望 OpenAI 格式的响应但实际拿到的是 Anthropic 格式或者反过来。比如你用 OpenAI 的 Python SDK把base_url设成https://taotoken.net/api但请求路径拼成了/v1/chat/completions而 TaoToken 在这个路径下返回的结构和 SDK 期望的不一致解析choices字段时就会报错。解决办法是确认你的 SDK 和 endpoint 匹配用 Anthropic SDK 就走/v1/messages用 OpenAI SDK 就走/v1/chat/completions不要交叉。如果你不确定先用curl手动发一个请求看返回的 JSON 顶层字段是content还是choices。curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:ping}]} | head -c 500第四个OAuth 相关报错。如果你用 Claude Code 的/mcp命令连接远程 MCP 服务可能会遇到 OAuth 认证失败。这个和翻译流程本身关系不大但如果你在翻译过程中顺手配置了 MCP就会碰到。排查方法是先确认 MCP 服务的 URL 和认证头是否正确再用claude mcp list看服务有没有被正确加载。如果报的是OAuth相关错误检查你的--header参数里Authorization的值有没有带Bearer前缀有些服务要求带有些不要求。除了请求层面的报错翻译质量层面也有几个高频问题。一是代码块被翻译表现为npm install -g anthropic-ai/claude-code变成了中文注释混排。这个要在切块阶段就跳过代码块或者在提示词里强调「代码块原样保留」。二是术语不一致比如同一篇文档里subagent一会儿译成「子智能体」一会儿译成「子代理」。这个靠术语表强制约束glossary_strict设为true时脚本会在翻译后做一次术语检查发现不一致就重新翻译那个块。三是表格错位表现为中文表头和英文内容对不齐。这个在翻译后要做一次表格结构校验确认列数没变。如果你在排查过程中需要对照接口文档接入文档入口是 https://taotoken.net/doc API Keys 管理入口是 https://taotoken.net/api-keys 。这两个页面在排查 401 和 endpoint 问题时最常用。6. 把翻译请求固定到 TaoToken长期维护与语义一致的收尾动作整套流程跑通之后最后一步是把它固定下来让后续的文档更新可以重复执行。这里的关键不是「一次性翻译完」而是「原仓库更新时中文版能低成本跟进」。具体做法是写一个sync.sh把拉取、翻译、校对、提交串起来#!/usr/bin/env bash set -euo pipefail EN_DIR./claude-code-guide-en ZH_DIR./claude-code-guide-zh # 1. 拉取英文原仓库最新内容 if [ -d $EN_DIR/.git ]; then git -C $EN_DIR pull --ff-only else git clone https://github.com/your-org/claude-code-guide.git $EN_DIR fi # 2. 对比文件哈希只翻译有变化的文件 python3 scripts/diff_files.py --mapping mapping.json --cache .translate-cache # 3. 批量翻译 python3 scripts/translate.py --config translate_config.json # 4. 校对术语一致性 结构对齐 代码块完整性 python3 scripts/review.py --config translate_config.json # 5. 输出报告 python3 scripts/report.py --output .translate-logs/report.mddiff_files.py的作用是计算每个英文文件的哈希和缓存里的哈希对比只把变化的文件交给翻译脚本。这样原仓库改了一个章节你只需要重新翻译那一个文件不用全量重跑。review.py做三件事扫描中文版全文检查术语表里的每个词是否按映射出现对比中英文版的标题层级确认 H2/H3 数量一致检查代码块数量是否一致防止翻译过程中代码块被吞掉。校对阶段可以用模型对话页面来辅助。把中文版的一个章节贴进去让模型检查「有没有术语不一致的地方」入口是 https://taotoken.net/models 。这个页面适合做抽样检查不适合全量跑因为全量校对还是脚本更高效。如果你打算长期维护这个中文版建议把翻译脚本和术语表都放进版本控制但 Key 和.env不要提交。术语表可以随着翻译过程不断补充比如你发现permission mode在原文里有两种译法就把它加进glossary.json下次翻译就会自动统一。目录映射也可以扩展原仓库新增了文件就在mapping.json里加一条。最后说一个实际经验翻译技术文档时最耗时的不是翻译本身而是校对。机器翻译出来的内容术语对了、结构对了但读起来还是有「翻译腔」。我的做法是第一遍用脚本全量翻译第二遍用模型对话页面逐章润色第三遍人工只读一遍专门看代码块和配置片段有没有被误伤。这三遍下来中文版的可读性会明显好于一次性翻译。如果你在长期维护过程中需要更稳定的调用额度可以了解一下 Coding Plan入口是 https://taotoken.net/coding-plan 。它更适合持续性的编码和 Agent 类任务文档翻译这种周期性任务按量调用 API 也完全够用。关键是无论你用哪种方式Base URL、Key、Model ID 这三件套保持一致翻译请求就始终走同一个通道不会因为换工具而重新配置一遍。