翻译文档
这一页写给译者，也写给改了英文段落、而这段已经有译文的人。本站同时发布英文版和简体中文版，中文页面在 /zh_CN/ 下，侧边栏可以随时切换。
页面先用英文写，再通过 Sphinx 的 gettext 流程翻译。译文按段落对应原文，而不是整份文件对应。哪一段还没有译文，就显示英文，所以站点总能完整构建出来。
make docs-gettext # extract one catalog template per page
make docs-translate DOCS_LANG=zh_CN # create or update that language's catalogs
# edit docs/developer/locale/zh_CN/LC_MESSAGES/*.po -- fill in msgstr
make docs-lang DOCS_LANG=zh_CN # build that language alone and read it
make docs-verify # what CI runs: the full site plus checks
catalog 里的每一条，都是一段英文原文配上它的译文：
msgid "Cloud Agent runs coding agents against a user's repository inside retained sandbox containers."
msgstr "Cloud Agent 在保留的沙箱容器中，针对用户的仓库运行编码 agent。"
英文原文本身就是查找译文的键。只要改了一段英文，这段的旧译文就自动失效，页面上改为显示英文，不会继续摆着一段和代码对不上的译文。这也是我们用 catalog、而不另写一份 .zh-CN.md 的原因：平行维护的文件过时了也没人察觉。
.po 文件要提交。docs/gettext/ 和编译出来的 .mo 文件都是生成的，已经在忽略列表里。
改了英文页面之后
运行 make docs-translate，把新增的条目和标成 #, fuzzy 的条目翻译好，再删掉 #, fuzzy 这一行，以及所有作废的 #~ 条目。只要还有一段英文没有对应的最新译文，make docs-verify 就不会通过。如果你自己翻不了，就在 pull request 里说一声，由能翻的评审者补上。
中文文风
要写成一位有经验的同事给你讲这一页时会说的中文，而不是把英文一句一句搬过来。先把整节读完，弄清楚它想告诉读者什么，再用中文把这件事说出来。理想的效果是，读者看不出这一页原本是用哪种语言写的。
事实一个都不能少。 自然不等于随意：英文里的条件、数字、默认值、步骤顺序和警告，中文里都要有，语气也不能减弱。英文没说的解释，也不要自己加。
长句要拆开重组。 英文习惯用从句把条件和细节挂在名词后面；中文一般先说条件、再说结果，长句拆成几个短句。名词前面堆了一串"的"，通常就说明有个从句应该单独成句。
英文离不开的代词和虚词，中文大多可以省掉。 英文里的 it、its、they，到了中文多半直接省略，或者换回它指代的名词。"进行"、每个名词前的"一个"、"能够"、"从而"，没有实际意思就别写。尽量用主动句，只有在被动本身就是重点时才用"被"。
翻意思，不翻字面。 That exact host 就是"这台主机"，不是"那台确切的主机"；runs agents against a repository 是"处理仓库"；buys inference 是"调用模型"。英文里的说法在中文里找不到对应时，就直接把意思讲明白。
跟读者说话。 在操作说明里称读者为"你"，"请"字少用。按读者实际操作的顺序，把要做的事一步步写清楚。
生硬 |
自然 |
|---|---|
Cloud Agent 在保留的沙箱容器中针对用户的仓库运行编码 agent。 |
Cloud Agent 让编码 agent 在保留的沙箱容器里处理用户的仓库。 |
编排器会等待，直到那台确切的主机仍报告 |
编排器会一直等到这台主机报告 |
授权部署就绪检查只接受这一台被命名的排空主机。 |
这样部署的就绪检查只会放行这一台正在排空的主机。 |
中文里的坑
前三个坑都不会报错：构建照样通过，页面却是错的。make docs-verify 里的结构检查能把它们揪出来。
代码、链接目标和标记一字不改。 行内代码、URL、链接目标、锚点、环境变量名和命令行都原样保留。链接只翻译显示的文字，目标绝不能动。检查会逐页比对译文和英文的行内代码与链接目标。
以数字开头的标题会丢失。 MyST 会把 1. 当成列表标记，结构和原文对不上，Sphinx 就退回去显示英文标题。把句点转义即可：msgstr "1\. 申请一个节点"。
加粗紧挨中文标点。 如果收尾的 ** 前面是中文句号、后面紧跟中文字符，它就不会被识别，**术语。**后文 会直接显示出星号。把标点挪到加粗外面：**术语**。后文。加粗文字以代码或引号开头、结尾时也一样，**`AGENT_TIMEOUT_S`**的默认值 会出错，要加一个空格：**`AGENT_TIMEOUT_S`** 的默认值。
旧的 .mo 会让你的修改看不出效果。 只要 .mo 比对应的 .po 新，Sphinx 就不会重新编译。检查构建结果之前，先运行 find docs/developer/locale -name '*.mo' -delete。
中文术语
同一个术语在所有页面都用同一个中文说法。产品名、组件名、以粗体显示的界面文字、API 字段、状态值和命令名保留英文。
英文 |
中文 |
|---|---|
control plane |
控制平面 |
host, execution host |
主机、执行主机 |
sandbox, sandbox group |
沙箱、沙箱组 |
retained sandbox |
保留沙箱 |
conversation, chat |
对话 |
task |
任务 |
turn |
轮次（一轮） |
follow-up |
后续消息 |
workspace |
工作区 |
snapshot |
快照 |
publish, publication |
发布 |
checkpoint |
检查点 |
archive |
归档 |
enroll, enrollment |
注册 |
heartbeat |
心跳 |
lease |
租约 |
claim |
认领 |
drain |
排空 |
fence |
栅栏 |
adopt (an issuer or existing data) |
认定 |
take over, takeover |
接管 |
checkout (noun / verb) |
本地仓库、仓库副本 / 检出 |
stack |
一套服务、环境 |
provider |
服务商 |
inference grant |
推理授权 |
credential |
凭据 |
token |
令牌 |
relay, tunnel |
中继、隧道 |
bridge |
网桥 |
resolver |
解析器 |
owner |
所有者 |
member |
成员 |
operator |
运维人员 |
administrator |
管理员 |
deployment |
部署 |
distribution |
发行版 |
migration |
迁移 |
native session |
原生会话 |
gateway |
网关（HybridInference Gateway） |
runner, Sandbox Manager, Fork, Kata, MCP, attempt, residency, execution profile |
runner、Sandbox Manager、Fork、Kata、MCP、attempt、residency、execution profile |