Markdoc

翻译 Markdoc 正文及选定的字符串属性,同时保留注解、变量和代码。

Markdoc 注解将文档正文与自定义组件和变量关联起来。markdoc 文件处理器会翻译受支持的正文和选定的字符串类型标签属性,同时保留渲染器所需的注解。

选择可见的标签属性 #

一份文档可以同时包含可见的元数据、固定的布局标识符和提示框:

markdown
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---

{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}

段落以及默认选中的前置元数据 title 和 description 都是文本。标签的 title 被属性规则选中后,也会纳入翻译范围。type="warning" 和 layout: article 是结构性标识符;除非使用它们的组件明确要求使用翻译后的值,否则请勿选中。

规则可以针对所有标签中的某个属性名生效,也可以仅针对指定标签中的该属性生效。如果不同标签将同一属性用于不同用途,建议限定标签范围。数值、布尔值、由变量派生的属性及其他非字符串属性,都不属于可直接翻译的正文单元。

哪些内容会受到保护 #

围栏代码块和行内代码不参与翻译。链接的目标地址保持不变,链接文本则可以更改。正文中的行内注解和图片属于受保护的结构。标签名和未选中的属性会保留在文档中。处理器会按照 Markdoc 的引号规则,对翻译后的字符串属性进行转义,但不会为渲染器提供自定义标签的模式定义。

前置元数据中的 title 和 description 默认选中。如果前置元数据的选择范围为空,它们将保持不变。选中映射或序列时,其下各级的标量值也会纳入翻译范围。如果相邻的路由字段或内容 ID 必须保持不变,请选择 seo.title 这样的精确路径。

保持源文与译文对齐 #

重建时,处理器会替换当前源文中的文本片段,也可以复用此前已对齐的源文与译文中的措辞。如果其中受保护的行内结构无法安全对应,复用就可能失败。请保留与已接受的译文对应的源文版本,尤其是在移动标签或更改链接之后。

不要认为包含 Markdoc 注解的 .md 文档会自动选用此处理器。CLI 会将 .md 识别为 Markdown;如果文档语言需要按 Markdoc 的方式处理,请显式指定格式。

配置 Markdoc 翻译 #

CLI 会根据 .mdoc 推断出 markdoc;不支持键作用域。使用 CLI 配置设置前置元数据、标签属性选择和目标布局,或使用 GitHub 运行仓库工作流。

使用站点的模式定义进行验证 #

文件处理器不会配置框架路由、内容加载或应用中的 Markdoc 转换。取回译文后,请使用与源文相同的模式定义来解析和渲染译文。检查翻译后的段落时,也请一并检查可见属性、链接目标地址、变量和选定的前置元数据。