故障排除
翻译文档中的章节锚点链接不起作用
像 [label](other.md#section-id) 这样的链接可能会打开正确的翻译文件,但无法滚动到目标标题 — 或跳转到错误的章节。片段 #… 在该区域设置中不再匹配任何标题 id。
常见原因:
- 源标题从未有过显式的锚点 ID;网站从可见的标题文本派生 slug,而该文本在翻译后会发生变化。
- 您在源文件中重命名了标题,但前面的
<a id="…"></a>行丢失或仍是旧 ID。 - 锚点链接使用了根据英文单词猜测的
#…片段,而不是write-heading-ids会生成的 ID。
修复
- 在你的 源
.md/.mdx(与translate-docs相同的docs[]/contentPaths)上运行ai-i18n-tools write-heading-ids。默认情况下,它会在每个 ATX 标题之前插入<a id="slug"></a>,或者在标题文本不再与当前 slug 匹配时刷新现有锚点。对于 Docusaurus MDX 注释 id,请使用--slug-style mdx-comment。 - 将锚点链接指向这些 id —— 例如
[setup](guide.md#first-run),其中#first-run与目标标题上方的锚点行匹配,而不是仅从英文标题推断出的 slug。 - 重新运行
translate-docs(或sync --force-update),以便每个语言环境的副本都包含更新后的锚点行。
首先在 write-heading-ids 上使用 --dry-run 预览更改。有关完整模式,请参阅锚点链接。
翻译文档中的图片或资产链接 404
Markdown 链接或  在英文版中有效,但在翻译版本中返回 404 错误 — 通常是因为 URL 仍然指向源语言环境文件夹或仅限英文的静态路径。
修复
- 确认您的资产布局与您的
docsOutput.style匹配(扁平式与文档系统)。请参阅链接重写和图片与截图。 - 添加或调整
docsOutput.postProcessing.regexAdjustments以交换区域设置段或桥接绝对/img/…路径。对于扁平式布局,请记住扁平链接重写器在 之前 运行regexAdjustments— 根据已添加前缀的 URL 匹配模式。 - 确保区域设置特定的资产文件存在于重写后的 markdown 引用的路径中(
translate-docs重写 URL 但不复制栅格文件)。
印度语、阿拉伯语、CJK 或西里尔语输出被罗马化(拉丁字母)
某些模型会翻译含义,但结果会以拉丁/罗马字母书写(例如,印度语为 Namaste 而非 नमस्ते)。裸 hi 指的是天城文;仅当您需要罗马化印度语时才使用 hi-Latn。
修复
- 确认区域设置代码与您想要的脚本匹配(
hivshi-Latn、zh-Hansvszh-Hant、srvssr-Latn)。 - 重新运行翻译以拒绝脚本错误的缓存行:对于 UI 字符串,请使用
translate-ui --force;或者使用translate-docs --check-cache/sync --check-cache(仅当区域设置具有预期脚本时,才会绕过文件级跳过;有效的片段缓存仍会重复使用)。--force-update会重新处理所有区域设置。 - 如果某个模型持续无法通过脚本检查,请为该区域设置添加一个
localeModels条目,以便首先尝试更强大的模型 — 请参阅 AI 模型。