翻译设置
此页面是配置界面：有哪些语言、使用哪个模型进行翻译、何时运行翻译流程、读者在哪里切换语言，以及每个翻译后的 URL 的格式。翻译流程的实际工作方式请参阅 AI 翻译；结果是否良好请参阅 翻译质量与 SEO。
自动翻译和翻译工作流控制属于付费计划的一部分 — 请参阅 定价。免费项目可以查看此页面上的所有内容，并且项目连接时仍会自动检测其源语言。但它无法更改其中任何内容：启用的语言和源语言属于同一个受计划限制的组，因此免费项目在这两项上都会被拒绝，翻译模式和启动翻译流程也是如此。
可配置的内容#
| 设置 | 功能 |
|---|---|
| 默认（源）语言 | 您的文档已经使用的语言。不会作为翻译目标。 |
| 启用的语言 | 您的文档还会以哪些语言发布。 |
| 翻译模型 | 执行翻译的 AI 模型。与聊天模型分开。 |
| 翻译模式 | auto、manual 或 external — 启动翻译流程的方式。 |
| 语言切换器 | 读者可以在侧边栏、页眉或两者中看到选择器。 |
项目的源语言#
Docsbook 会检测文档所使用的语言，而不是要求您指定语言。项目连接后，它会读取仓库 README，去除代码围栏、内联代码、图片、链接和 HTML，然后对剩余内容运行语言识别器。
需要注意的规则：
- 去除上述内容后，说明文字少于 50 个字符，或无法得出有把握的结果时，会回退到
en，并以低置信度记录，因此面板会标记为最佳猜测 — 请确认，而不是将猜测呈现为检测结果。有把握的检测结果会以高置信度记录，并标记为自动检测。自行设置后会重新标记为由您设置，并固定该设置。 - 检测器仅识别 Docsbook 支持的十五种代码。使用不在该集合中的语言编写的 README 将回退到
en。 - 源语言永远不能启用为翻译目标。如果您传入源语言，它会从
enabled_languages中被删除，并且翻译过程会明确跳过它——甚至在检查该语言是否已启用之前——跳过原因是is_source_language。这是结构性保护，而非 UI 验证：过时的数据库记录或直接的 API 调用都无法让项目付费将英语翻译成英语。 - 英语并不特殊。文档使用德语编写的项目，同样适用上述规则的镜像情况。
启用语言#
- 打开您的文档站点。
- 浮动小组件 → 翻译选项卡。
- 勾选所需的语言。
- 确认对话框。处理将在后台开始。
如果语言切换器已位于您的站点上，打开它并按下激活语言会转到同一选项卡。该入口仅对您（站点所有者）显示，或在管理员预览中显示——读者永远看不到。
启用语言本身不会在 API 层面翻译任何内容：update_languages 设置集合，而 run_translation_pass（或该模式自身的触发器）执行实际工作。在面板中，这两者已为您合并，因此勾选复选框确实会启动一次处理。
对话框会先列出运行费用#
在花费任何费用之前，确认对话框会显示总页数中尚未翻译的页数、预计费用以及剩余余额。如果余额不足以完成本次运行，它会说明余额可以覆盖文档的比例，并提供充值选项——而且翻译符合余额的部分确实是一个可选项：余额足够的页面会立即翻译，其余页面会在余额允许时自动继续处理。
预计费用根据您所选择的模型计算，因此报价和实际扣费对应的是同一个模型。必须明确说明这一点，因为过去曾出现过不一致的情况：预计费用按一个模型计算，而运行时却使用了另一个模型。
选择翻译模型#
设置 ▸ 翻译 ▸ 翻译模型用于选择模型，并且它特意与读者聊天所使用的模型分开设置——翻译文章和使用工具回答问题是两项不同的工作，影响其中一项的衡量指标没有理由影响另一项。
如果不做选择，选择器中会显示默认标记为 (default) 的模型，目前是 GPT-5.6 Luna。每个选项都会显示其每 100 万个词元的价格，因此更便宜的模型可以将余额用于更多页面，而当某种语言的翻译效果不佳时，只需单击一下即可切换到更强的模型。在托管模式下，仅 Docsbook 目录中的模型会被认可，因为费用按模型公布的价格计费，而无法识别的模型会按照你从未看到过的费率收费。
如果你使用自己的翻译 API 密钥，该卡片中的模型会变为自由文本字段，并且运行费用由你自己的提供商承担，而不是从项目余额中扣除。使用自己的密钥并不会解锁免费项目中的翻译功能：这是一项套餐限制，而不是费用问题。
选择翻译运行的时机#
| 模式 | 触发一次翻译的条件 |
|---|---|
| 自动 | 更改已记录页面的推送会将该页面重新加入每种已启用语言的翻译队列。 |
| 手动 | 不会自动启动任何操作；您需要按下立即翻译或请求代理。 |
| 外部 webhook | 不会自动启动任何操作；Docsbook 会发出 translation.needed，由您自己的流水线决定后续操作。 |
在自动模式下，Docsbook 会轮询您的代码仓库，而不是响应 webhook：大约每 15 分钟检查一个工作区，并且每次只检查四个工作区，因此请预计追赶翻译会在大约这个时间窗口内开始，而不是在您推送后立即开始。已经落后的页面会优先于从未翻译过的页面进行翻译——过时的翻译会主动向读者传达文档已不再表达的内容，而缺失的翻译则会回退到原文，只是无法提供帮助。
代理使用 set_translation_mode MCP 工具设置模式：
// auto: Docsbook follows new commits and re-translates the pages they changed
set_translation_mode({ workspace_id: 42, mode: "auto" })
// external: nothing runs here; your pipeline listens for translation.needed
set_translation_mode({ workspace_id: 42, mode: "external", external_webhook_url: "https://example.com/hooks/translate" })在 external 模式下，您会收到一个 translation.needed 事件，运行自己的流水线，然后使用 upload_translation 将结果发回。设置 external 时，如果之前从未提供 webhook URL，系统会拒绝该设置，而不是默默接受。
语言切换器位置#
切换器可以显示在侧边栏、页眉中，或同时显示在两者中。页眉位置是独立的工作区标志；侧边栏还可以设置为仅在移动设备上显示切换器，因此宽屏桌面页眉会包含它，而窄屏布局不会重复显示。
| 位置 | 最适合 |
|---|---|
| 页眉 | 更加醒目；当面向国际受众是重点时更合适 |
| 侧边栏 | 页眉已经很满时可以节省页眉空间 |
选择一个即可。在同一屏幕上显示两次相同的控件只会造成干扰。请在页眉选项或侧边栏控件中进行配置。
如果网站没有启用任何语言，则完全不会显示切换器，而不是显示一个包含单个条目的控件。
翻译页面的 URL#
区域设置始终是路径段，而不是子域名。不存在 https://fr.docsbook.io/…，并且裸语言子域名会被故意以 404 响应提供，这样它就不会成为相同内容的第二个地址。
https://<user>.docsbook.io/<repo>/<path> → your source language
https://<user>.docsbook.io/fr/<repo>/<path> → French
https://<user>.docsbook.io/ja/<repo>/<path> → Japanese在自定义域名上，仓库段会消失，而区域设置会保留在开头：
https://docs.example.com/<path> → your source language
https://docs.example.com/fr/<path> → French有两个值得了解的后果：
- 使用自定义域名的工作区以该域名为规范地址，而不是以其
docsbook.io镜像为规范地址——翻译页面和原始页面均如此。混用二者会发布一个页面，其hreflang邻近页面指向的位置与其自身的规范地址不一致。 /en/…存在，但不是单独的页面。英文内容在/<repo>/<path>和/en/<repo>/<path>上完全相同地提供，带前缀的形式将不带前缀的形式声明为其规范地址，因此这两个地址会合并为一个可编入索引的页面，而不是彼此竞争。
某些由 Docsbook 托管的网站——产品自身的文档和展示项目——会在顶级域名上提供，并将区域设置置于仓库段之后（https://docsbook.io/<repo>/fr/<path>）。Docsbook 使用与路由这些页面相同的函数，为其生成规范地址和 hreflang，因此它所公布的 URL 始终是返回 200 而非重定向的地址。
关闭某种语言#
在“翻译”选项卡中取消选中它，或使用该语言专属页面上的开关。系统不会要求确认，因为不会销毁任何内容：
- 已存储的翻译会保留。重新启用该语言后，对于未发生变化的页面不会再次收费——只有新增和编辑过的页面会被翻译，因此重新启用以前使用过的语言几乎可以立即完成，且几乎不产生费用。
- 该语言的报告页面也会保留，因此可以根据它已有的读者和成本来判断“我应该重新启用它吗？”
- 访问已停用语言网址的读者会被转到您的源语言版本。
限制#
- 十五种代码，不提供地区变体。
pt通过一套页面覆盖巴西和葡萄牙；zh通过一套页面覆盖简体和繁体。存储的语言列允许五个字符，因此可以存储类似pt-BR的代码，但产品中没有任何功能会生成或提供这些代码。 - 自动模式是轮询，而不是 webhook。 推送会在下一次扫描时被获取，而在工作区繁忙的情况下，单个工作区两次扫描之间的等待时间可能超过 15 分钟。如果大约一小时内都没有扫描你的项目，按语言划分的面板会将扫描标记为逾期，而不会假装它仍按计划进行。
- 语言切换器是唯一面向读者的语言控制项。 Docsbook 不会根据
Accept-Language重定向读者，也不会根据地理位置为其路由；未表达任何偏好的读者将看到网站配置的默认语言。 - 模型选择按工作区设定，而不是按语言设定。 在同一个项目中，你不能使用比波兰语更强的模型来翻译日语。