文档
translate-docs 的参考,这是用于处理在 docs[] 配置块中列出的 Markdown、MDX、.astro 和纯 HTML 页面的流水线。每个块的 contentPaths 字段列出了要翻译的文件或文件夹。这些文件以 sourceLocale 编写,可以是任何语言。示例中的英语只是一个例子。首次向网站添加语言?请从向网站或文档站点添加 i18n开始。对于仓库 README 和其他通常与应用放在一起的 Markdown 文件,请参阅向 README 和 Markdown 文档添加 i18n。HTML 页面中描述了纯 HTML 页面(每个区域设置一个文件)。
框架外壳字符串(导航栏、侧边栏、主题)在同一次运行中翻译,而不是通过单独的流水线。下表中的框架指南说明了每种框架的实现方式:Docusaurus 使用 docusaurusCatalogDir,VitePress 使用 docsOutput.vitepressThemeCatalog,Nextra 使用 docs[].nextraDictionaryPath,Fumadocs 使用 docsOutput.fumadocsUiCatalog。Nextra _meta.ts 和 Fumadocs meta.json 的侧边栏标签是自动收集的。Astro Starlight 为许多区域设置提供了内置的 UI 字符串,可选的覆盖项可以在 docs[] 块上使用 jsonPathTemplate。
对于嵌入在 Markdown 中的 PNG 和其他栅格图像,请参阅图像和屏幕截图。translate-docs 仅翻译替代文本;它不复制栅格文件。
如需在 README 或文档中添加可选的 语言切换器 块,请将 docsOutput.style 设置为 "flat"——参见语言切换器。
SVG 文件在启用 features.translateSVG 时通过 translate-svg 进行翻译——而非通过 docs[] / contentPaths。
与文档框架的外壳/主题字符串无关的任意嵌套 UI JSON 包属于 JSON 管道,而不属于 docs[]。
每个 UI 区块默认包含其 strings.json 作为文档的术语表提示(uiGlossary,默认值为 true)。当段落中出现匹配术语时,translate-docs 会复用这些翻译作为 LLM 提示词中的提示。对于不应出现在文档提示词中的目录,请将 uiGlossary 设置为 false。可选的 glossary.userGlossary 可为产品术语添加 CSV 覆盖(与 translate-ui 和 proofread-ui 共享)。为适应窄列而使用的紧凑 UI 标签缩写(例如 Size → Tam)仍可用于 UI 翻译,但会从文档术语表提示中省略。使用 glossary-generate 生成初始 CSV,在翻译仪表板的 术语表 选项卡中编辑行,或参阅 配置 — glossary 和 术语表。
每个区域模型覆盖
translate-docs 和 sync 的文档步骤会 根据目标语言环境 解析模型:如果已配置,则优先使用 localeModels(locale),然后是提供商的全局 translationModels 链。当特定语言需要与默认备用列表不同的模型时,请使用此功能——例如,当全局链难以处理葡萄牙语时,在 pt-BR 文档中优先使用 Gemini。请参阅 AI 模型 和 配置 - localeModels。
阅读哪个指南
| 你的配置 | 从这里开始 |
|---|---|
| Docusaurus 站点 | init -t ui-docusaurus、docsOutput.style = "docusaurus" — Docusaurus |
| VitePress 站点 | init -t ui-vitepress + vitepressThemeCatalog 用于主题 — VitePress |
| Nextra 站点 | init -t ui-nextra + nextraDictionaryPath 用于字典(侧边栏 _meta.ts 是自动的)— Nextra |
| Fumadocs 站点 | init -t ui-fumadocs + fumadocsUiCatalog 用于 UI(侧边栏 meta.json 是自动的)— Fumadocs |
| Astro Starlight | init -t ui-starlight — Astro Starlight |
| 纯 HTML 页面 | init -t docs-plain-html - HTML 页面 |
| 扁平文档(README、更新日志等) | 向 README 和 Markdown 文档添加 i18n — init -t docs-markdown 或 --with-readme。布局:输出布局、语言切换器 |
| 翻译文件存放位置 | 输出布局 |
跨页面 #anchor 链接 | 锚点链接 |
链接和资产 URL 重写 (regexAdjustments) | 链接重写 |
| 文档中的屏幕截图 | 图像和屏幕截图 |
| 产品术语与 UI/文档一致性 | 配置 — glossary、术语表 |
translate-docs 标志和缓存 | CLI 选项 |
步骤 1:初始化文档
ai-i18n-tools init -t ui-docusaurus -P openai适用于 Astro Starlight 文档网站:
ai-i18n-tools init -t ui-starlight -P cheaperinference对于 VitePress 文档站点:
ai-i18n-tools init -t ui-vitepress -P anthropic为导航/侧边栏/页脚字符串设置 docsOutput.vitepressThemeCatalog——参见 VitePress 集成。
对于 Nextra 文档站点:
ai-i18n-tools init -t ui-nextra -P gemini为主题字典字符串设置 docs[].nextraDictionaryPath——参见 Nextra 集成。侧边栏 _meta.ts 标签会自动收集。
对于 Fumadocs 文档站点:
ai-i18n-tools init -t ui-fumadocs -P groq为 UI 覆盖设置 docsOutput.fumadocsUiCatalog——参见 Fumadocs 集成。侧边栏 meta.json 标签会自动收集。
适用于纯 Astro 网站 UI(无 Starlight):
ai-i18n-tools init -t ui-astro-website -P ollama该模板仅启用 UI 提取。对于页面 HTML 翻译,还需设置 features.translateDocs 并添加一个 docs[] 块(请参阅Astro 网站页面(解析和替换))。examples/astro-website 配置一起展示了这两种流水线。
编辑生成的 ai-i18n-tools.config.json:
provider和providers—init -P <provider>会搭建该预设;请在translate-docs或sync之前设置其 API 密钥(Ollama 不需要密钥)。请参阅提供商和 API 密钥、LLM 提供商和AI 模型。sourceLocale- 源语言(必须与docusaurus.config.js中的defaultLocale匹配)。targetLocales- BCP-47 区域设置代码数组(例如["de", "fr", "es"])。cacheDir- 适用于所有流水线的共享 SQLite 缓存目录(以及--write-logs的默认日志目录)。docs- 文档块数组。每个块包含可选的description、contentPaths(字符串或数组;文件、目录或 glob)、outputDir、可选的docusaurusCatalogDir、docsOutput、可选的segmentSplitting、translateFrontmatterFields、protectAttributes、protectKeys、targetLocales、addFrontmatter等。docs[].description- 为维护者提供的可选简短说明。设置后,它会显示在translate-docs标题和status章节标题中。docs[].contentPaths- markdown/MDX/.astro源文件(以及用于 Docusaurus shell JSON 的可选docusaurusCatalogDir)。docs[].outputDir- 该块的翻译输出根目录。docs[].docsOutput.style-"nested"(默认)、"flat"、"doc-system"或别名"docusaurus"/"astro-starlight"/"vitepress"/"nextra"/"fumadocs"(请参阅 输出布局)。ui[].uiGlossary- 当为true(默认值)时,该区块的strings.json会为文档段落提供术语提示(请参阅 配置 —ui)。glossary.userGlossary- 用于固定产品术语翻译的可选 CSV;也用于 UI 流水线,并可在 术语表 仪表板选项卡中编辑。
主要与补充: 专注于 contentPaths 用于本地化页面。当您还需要来自 write-translations 的 Docusaurus shell JSON 时,请设置 docusaurusCatalogDir。如果您只翻译页面,请省略 docusaurusCatalogDir。
步骤 2:翻译文档
ai-i18n-tools translate-docs这会将每个 docs[] 块的 contentPaths 中的所有文件(以及设置 docusaurusCatalogDir 时的 Docusaurus 目录 JSON)翻译为所有有效的文档语言环境。已翻译的片段将从 SQLite 缓存中提供 - 只有新增或更改的片段才会发送到 LLM。
翻译单个区域设置:
ai-i18n-tools translate-docs --locale de检查需要翻译的内容:
ai-i18n-tools status有关标志、缓存行为和批量提示格式,请参阅CLI 选项。
复杂的 Markdown 和未通过的质量检查
translate-docs 会检查每个已翻译的段落是否保留了 markdown 结构(包括从文档解析出的强调标记),以及内部占位符标记是否能干净地还原。在一段话中堆叠大量 bold 片段并围绕 `inline code`、在加粗中嵌套反引号(例如模板字面量 `fetch(\`/locales/${code}.json\`)`),或在长句中交织加粗与代码的写法都很脆弱:某些语言区域需要不同的语序,这会改变翻译后 ** 与 ` 的对齐方式,并触发诸如 AST mismatch 之类的 CLI 错误。
在恢复后,translate-docs 也会拒绝重用或丢弃了 HTML 标签占位符的片段(因此恢复的标签不再与源映射匹配),或者模型生成了源中不存在的多余双花括号标记(例如编造的词汇表样式标记)的片段。恢复前的检查要求 {{…}} 标记的多重集相同,且结构标记({{HTM_N}}、警告标记)的有序子序列相同;当每个 id / 类型的计数仍然匹配时,诸如 {{ILC_N}}、{{URL_N}} 等内容标记以及像 {{SE}} 这样的强调标记可以随自然语序移动。这些失败情况使用与多余的官方内部标记相同的模型回退路径。
如果您遇到此类验证失败,建议优先简化源语言文本 - 拆分段落、将示例移入围栏代码块,或者用更少的嵌套粗体/代码对来描述相同的概念 - 而不是期望每个模型和语言环境都能完美重现密集的内联标记。
当用于某个片段的模型以 AST mismatch 失败时,translate-docs 可以自动将该片段拆分为更小的部分(首先是列表中间点,然后是单个列表项或更短的段落块),从第一个模型重试每个部分,并将结果在原始片段缓存键下重新组合。相同的质量错误出现三次会提前停止模型列表;不同的错误则会继续。此功能默认开启 (segmentSplitting.qualityRetrySplit);将其设置为 false 以在模型列表结束后停止。当此回退机制运行时,运行摘要会报告 Quality split retries。
要查看哪些段落失败了、失败频率以及存储的质量/错误消息,请使用翻译仪表板的失败选项卡(翻译仪表板 → 失败)。