语言切换器 (languageListBlock)
使用 docsOutput.postProcessing.languageListBlock 时,翻译的 markdown 文件应包括一个 "阅读其他语言" 行链接 —— 每个语言区域一个链接,具有相对于每个输出文件的 href 值。
此存储库将其用于 README.md(translated-docs/ 下的平面输出)。在 translate-docs 之后,每个翻译副本都会获得一个刷新的块;例如,translated-docs/README.de.md 链接到 translated-docs/ 下的同级区域设置文件,并链接回存储库根目录的英文源。
需要 docsOutput.style = "flat"(或其他可按相对路径寻址同级区域设置文件的布局)。请参阅输出布局。首次将此添加到仓库 README 中:将 i18n 添加到您的 README 和 Markdown 文档中。
1. 在源 Markdown 中标记块
将切换器包装在由 start 和 end 子字符串标记分隔的 HTML(或任何行)中。此存储库使用:
<small>**Read in other languages:** </small>
<small id="lang-list">[English (GB)](/zh-Hans/) · [Deutsch](./README.de.md) · …</small>初始链接文本只是一个占位符。translate-docs 会替换从包含 start 的第一行到包含 end 的第一行之后的整个切片(在围起来的代码块中的标记将被忽略,因此同一文件中的配置示例不会匹配)。
2. 配置块
start 和 end 是任意的子字符串标记 — 它们不必是 <small id="lang-list"> / </small>。选择仅出现在语言切换器切片中的任何开始和结束文本:另一个 HTML 标签 (<div class="lang-switcher"> … </div>)、HTML 注释 (<!-- lang-list --> … <!-- /lang-list -->) 或仅限 Markdown 的边界(例如,一行 **Languages:** 到一行 ---)。在配置中设置 start 和 end 以精确匹配您在源文件中放置的内容。
根配置 (ai-i18n-tools.config.json):
"postProcessing": {
"languageListBlock": {
"start": "<small id=\"lang-list\">",
"end": "</small>",
"separator": " · "
}
}| 字段 | 作用 |
|---|---|
start | 标识块开始行的子字符串 |
end | 结束行上的子字符串(当两者都出现在一行时,可以与 start 相同) |
separator | 生成的 [label](href) 链接之间的文本(此仓库使用 " · ") |
label | 可选:"local"(默认)使用清单中的每个区域设置的本地名称;"english" 使用 englishName |
3. 运行时发生的情况
- 提取 — 语言列表切片不会发送给模型(
translatable: false)。 - 每个已翻译文件 — 在片段翻译和可选的扁平链接重写之后,
postProcessing会重建该块:每个区域设置一个 Markdown 链接;标签优先来自ui-languages.json(如果存在),否则来自捆绑的主目录,否则来自localeDisplayNames;路径相对于正在写入的文件。 - 源刷新 — 在一次
translate-docs/sync文档处理结束时,同一个规范块会写回contentPaths中的源区域设置文件,因此添加区域设置会更新存储库中的切换器,而无需手动编辑每个链接。这些文件以sourceLocale写入,可以是任何语言。
如果文件没有匹配的块,CLI 会记录一个警告(当 --verbose 时)并保持正文不变。
4. 标签清单
对于内名标签(label: "local"),通过 generate-ui-languages 生成或维护 ui-languages.json(写入 languagesManifestPath,默认为 {ui.flatOutputDir}/ui-languages.json)。此仓库的仅文档配置没有 UI 流水线,磁盘上也没有项目清单,因此标签来自 sourceLocale + targetLocales 的内置主目录。
5. 此存储库中的示例
| 示例 | 文件 |
|---|---|
| 本包(扁平 README + VitePress 站点) | ai-i18n-tools.config.json(README 块:docsOutput.style = "flat";站点块:docsOutput.style = "vitepress" + vitepressThemeCatalog) |
| 平面 README + Docusaurus 文档 | examples/nextjs-app/ai-i18n-tools.config.json (第二个块: docsOutput.style = "flat"; 第一个块: docsOutput.style = "docusaurus") |
| 仅限 Docusaurus 文档 | examples/docusaurus-docs/ai-i18n-tools.config.json (docsOutput.style = "docusaurus" + docusaurusCatalogDir) |
| VitePress 文档(最小演示) | examples/vitepress-docs/ai-i18n-tools.config.json (docsOutput.style = "vitepress" + vitepressThemeCatalog) |
<small id="lang-list"> 前面的那一行(例如 **Read in other languages:**)是一个正常的、可翻译的片段,并在每个目标区域设置中本地化;只有标记内的链接行会逐字重新生成,除了 href 和清单驱动的标签。
HTML 页面
纯 HTML 文档使用另一对注释 <!-- ai-i18n:lang-list --> 和 <!-- ai-i18n:hreflang -->。语言列表可以是链接或 <select>,并且 hreflang 备用项会写入源区域设置文件以及每个目标区域设置文件中。请参阅HTML 页面。