Markdown

翻译文档正文和选定的前置元数据,同时保留代码、链接及复用已认可译文所需的结构。

Markdown 文档通过说明性文本和清晰的结构,帮助读者理解内容。md 文件处理器会翻译标题、段落、表格单元格和受支持的指令标签中的文本,同时保护代码和链接目标。输出仍为 Markdown 格式,可继续使用现有渲染器。

文本与受保护的结构 #

例如,链接文本可以翻译,而链接目标和函数名保持不变:

markdown
---
title: Delivery options
description: Choose how your order arrives.
slug: delivery
---

## Choose delivery

Read the [delivery policy](/policies/delivery) before calling `confirmOrder()`.

标题、段落内容和链接文本属于可翻译文本,链接目标和行内代码则属于受保护的结构。在常规文档处理配置下,围栏代码块和原始 HTML 不纳入正文提取范围。如果源文件是 HTML 文档,请使用 HTML;如果文档语言包含自定义 Markdoc 标签,请使用 Markdoc。

选择前置元数据 #

默认情况下,文件处理器会选择 title 和 description。其他字段除非明确选中,否则保持不变。将 translateFrontmatterFields 列表设为空,即可关闭前置元数据翻译。字段的选择应根据内容决定:供人阅读的标题可以翻译,而 URL 别名、组件标识符或路由键可能需要保持不变。

受支持的字段路径可以定位嵌套值,包括序列中的成员。选择映射或序列时,会一并选中其下所有标量值。如果相邻的路由字段必须保持不变,请使用 seo.title 这样的精确路径。通过所选接口的前置元数据选项,指定要翻译的文本。

复用译文需先对齐文档 #

处理器会将文本单元与先前的源文档及其对应的目标文档进行匹配,再将有变更的译文插入当前源文档的结构中。只有对应关系明确,才能复用现有译文。如果先前的源文档与目标文档包含不同的受保护行内结构,复用可能因结构不匹配而失败。

请保留与已认可译文对应的源文档版本。如果目标文档的结构经过单独调整,请先将其结构与该源文档对齐,再请求增量更新。使用站点的 Markdown 处理器构建输出结果,检查特定 Markdown 方言的语法结构。

配置并渲染文档 #

CLI 会根据 .md 推断 md。在 CLI 配置中设置文件选择、前置元数据字段和输出路径,或通过 GitHub 以托管方式翻译代码仓库。Markdown 不支持 CLI 的键范围功能。

使用站点的 Markdown 处理器渲染输出,并一并检查翻译后的元数据、链接、标题片段标识符和代码示例。保留 /policies/delivery 并不会创建该页面的其他语言版本。静态内容指南介绍了如何将输出路径与站点的加载器及语言区域路由衔接起来。