Translating the docs

This page is for translators, and for anyone whose English edit changes a paragraph that has a translation. The site is published in English and Simplified Chinese; the Chinese pages are at /zh_CN/ and the sidebar switches between them.

The pages are written in English and translated with Sphinx’s gettext workflow, so a translation is attached to each paragraph of source text rather than to a whole file. Any string without a translation falls back to English, so the site always builds complete.

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

A catalog entry pairs the English source with its translation:

msgid "Cloud Agent runs coding agents against a user's repository inside retained sandbox containers."
msgstr "Cloud Agent 在保留的沙箱容器中，针对用户的仓库运行编码 agent。"

The English text is the lookup key, so editing a paragraph invalidates its translation automatically: the page falls back to English for that paragraph instead of serving a translation that no longer matches what the code does. That is the reason to use catalogs rather than parallel .zh-CN.md files, which drift silently.

Commit the .po files. docs/gettext/ and compiled .mo files are generated and ignored.

When you change an English page

Run make docs-translate and translate the entries it adds or marks #, fuzzy, then delete the #, fuzzy line and any obsolete #~ entries. make docs-verify fails until every English string has a current translation. If you cannot translate a change yourself, say so in the pull request; a reviewer who can will add it.

Chinese style

Write the Chinese an experienced colleague would write to explain the page, not a sentence-by-sentence rendering of the English. Read the whole section first, work out what it is telling the reader, and then say that in Chinese. A reader should not be able to tell which language the page was written in.

Keep every fact. Natural is not looser: a condition, a number, a default, an order of steps or a warning in the English stays in the Chinese, with the same strength. Do not add explanations the English does not give.

Rebuild long sentences. English hangs conditions and details off a noun in relative clauses; Chinese states the condition first and then the result, and splits a long sentence into short ones. A string of 的 in front of a noun is the usual sign that a clause should become its own sentence.

Drop the pronouns and filler English needs. Most it, its and they disappear in Chinese or become the noun they stand for. Leave out 进行, 一个 in front of every noun, 能够 and 从而 unless they carry meaning. Prefer the active voice; use 被 only when the passive is the point.

Translate the meaning, not the word. That exact host is 这台主机, not 那台确切的主机; runs agents against a repository is 处理仓库; buys inference is 调用模型. When an English idiom has no direct Chinese equivalent, say plainly what it means.

Talk to the reader. Address the reader as 你 in instructions, and use 请 sparingly. Spell out what to do in the order they will do it.

Stiff	Natural
Cloud Agent 在保留的沙箱容器中针对用户的仓库运行编码 agent。	Cloud Agent 让编码 agent 在保留的沙箱容器里处理用户的仓库。
编排器会等待，直到那台确切的主机仍报告 draining。	编排器会一直等到这台主机报告 draining。
授权部署就绪检查只接受这一台被命名的排空主机。	这样部署的就绪检查只会放行这一台正在排空的主机。

Chinese traps

The first three are silent: the build stays green and the page is wrong. The structural check in make docs-verify catches them.

Keep code, link targets and markup exactly. Inline code, URLs, link targets, anchors, environment variable names and command lines stay as they are. Translate a link’s text, never its target. The check compares the inline code literals and link targets of each translated page with the English one.

A heading that starts with a number is dropped. MyST reads 1. as a list marker, the structure no longer matches the source, and Sphinx emits the English heading. Escape the period: msgstr "1\. 申请一个节点".

Emphasis next to Chinese punctuation. A closing ** preceded by a Chinese full stop and followed by a Chinese character is not recognised, so **术语。**后文 shows literal asterisks. Put the punctuation outside the bold: **术语**。后文. The same applies when bold text starts or ends with code or a quotation mark: **`AGENT_TIMEOUT_S`**的默认值 breaks, so add a space, **`AGENT_TIMEOUT_S`** 的默认值.

A stale .mo masks your edits. Sphinx skips recompiling when the .mo is newer than its .po. Before checking a build, run find docs/developer/locale -name '*.mo' -delete.

Chinese terminology

Use the same Chinese for a term on every page. Product and component names, UI labels shown in bold, API fields, states and command names stay in English.

English	Chinese
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