MDX
翻译 MDX 正文及选定的组件字面量属性,同时保留表达式、导入语句和组件结构。
MDX 让文章能在正文中嵌入交互式组件。mdx 文件处理器会翻译受支持的正文和组件子内容,同时保留原有标记。如果组件的字面量属性也包含读者可见的文字,请明确选中这些属性;处理器不会通过执行导入语句或表达式来查找文本。
区分正文与组件数据 #
例如,提示框既有可见的标题,也有控制其行为的属性:
import Callout from "./Callout";
## Delivery options {#delivery}
<Callout title="Delivery deadline" kind="warning">
Confirm your address before checkout.
</Callout>标题和子内容中的正文属于待翻译文本。kind 是组件数据,应保持不变。只有被组件属性规则选中时,title 才会纳入翻译范围。将规则限定为 Callout 和 title,比翻译所有不相关组件中的同名属性更安全。
支持以字符串字面量形式定义的属性。通过表达式计算得出的属性并不等同于字面量消息。导入语句、JavaScript 表达式和代码块不在常规正文提取范围内。组件结构仍需与应用的渲染器匹配。
前置元数据与标题锚点 #
文件处理器默认选中前置元数据中的 title 和 description。将选择配置设为空,即可保留前置元数据而不作翻译。选中映射或序列时,其下所有层级的标量值都会纳入翻译范围。因此,如果相邻的路由字段必须保持不变,请选择 seo.title 这样的精确路径。有关 translateFrontmatterFields 和 translateComponentProps,请参阅 CLI 配置。
标题文本变化时,{#delivery} 等 Docusaurus 标题锚点会受到保护。锚点处理会识别围栏代码块之外的标题行语法,并保持 URL 短标识不变。请在站点中验证渲染后的标题 ID 及指向该标题的链接。
更新与对齐 #
如果上一版源文与译文的文本单元及受保护的行内结构相互对应,就可以沿用现有译文。如果对应关系不明确,处理器可能会拒绝复用。请将已接受的译文与对应的源文修订版本配对保存,不要在未作说明的情况下提供结构不相关的文档。
重建后,请检查选定的属性,包括子内容正文之外的可见标签,再使用应用的 MDX 处理器构建结果。
配置 MDX 翻译 #
CLI 会根据 .mdx 推断 mdx;此格式不支持键范围。有关文件选项,请参阅 CLI 配置或 GitHub。
检查渲染后的组件 #
使用实际采用的处理器构建获取到的 MDX,并一并检查组件属性、锚点、变量和代码示例。MDX 文件翻译会保留包含 JSX 的文档;而 React 消息提取会在应用源代码中查找受支持的调用,并生成消息目录。请根据消息的编写位置选择相应的工作流。