内联令牌 (Inline tokens)

MDX 正文通常需要使用 Scribe 已经知道的值，例如指向其他条目的链接、资源的公共 URL、绝对不能翻译的字面量，或者在多个地方重复使用的每个文档特有的小字符串。硬编码这些值会使正文变得脆弱（重命名的 slug 或移动的资源会悄悄地破坏链接），并污染翻译（URL 绝不应该被“翻译”）。

内联令牌解决了这个问题。你只需在英文正文中编写一次令牌，它就会在读取时针对每种语言进行解析，而翻译过程会将其视为不透明、不可变的占位符。

语法

令牌的格式为 ${{<kind>:<args>}}。共有四种类型：

令牌	解析为
${{static:"text"}}	逐字字面量 text（一个 JSON 字符串，因此引号和转义符定义明确）。不被翻译，在所有语言环境中完全相同。
${{relation:<typeId>:<enSlug>:href}}	指向目标条目的链接路径（请参阅关联模式）。模式后缀是必需的。
${{relation:<typeId>:<enSlug>:slug}}	目标的英文 slug 字符串，这是用于自己加载 Scribe 内容的 MDX 组件的稳定标识符。
${{asset:/web/path.webp}}	公共资源 URL（assets.publicPath 连接到路径）。请参阅资源。
${{var:key}}	同一文档的 frontmatter.vars[key]。

Slug 不能包含 :，因此关联解析是明确无误的。没有模式后缀的光秃秃的 ${{relation:<typeId>:<enSlug>}} 属于验证错误。

关联模式

每个关联令牌都必须以 :href 或 :slug 结尾。

模式	用途
:href	可导航链接。解析后的形状取决于消费者（见下文）。
:slug	身份标识：始终是目标的英文 slug 字符串。

:href 的解析方式取决于文档的读取者：

消费者	:href 解析为
createScribe()（应用运行时）	带有本地化 slug 的无语言环境路径名（例如 /for/vestidos），可直接传递给你的路由器的 Link。
静态 .md 导出	带有文件扩展名的完整本地化公共路径（例如 /es/for/vestidos.md），与导出文件布局相匹配。

转义途径

${{（美元符号和大括号之间的反斜杠）渲染字面的 ${{ 且绝不被视为令牌。在文档内容中使用它来展示令牌语法，本页面正是如此。

vars frontmatter 键

vars 是一个可选的 Record<string, string>，任何条目都可以声明它而无需将其添加到类型模式中：

---
title: 春季促销
vars:
  cta: 立即抢购
---

准备好了吗？${{var:cta}}。限时优惠。

vars 是保留键，它在模式验证之前被提取（因此严格的模式绝不会拒绝它），并且绝不会被视为可翻译字段，它仅存在于英文文档中。翻译后的文档从其英文父级的 vars 映射中读取 ${{var:key}}，从而保证了唯一事实来源。

哈希与翻译

令牌在哈希处理前被提取。每个令牌都会被替换为一个惰性的编号标记（按出现顺序为 %%1%%、%%2%% 等），而这个包含占位符的正文才是经过哈希处理并发送给翻译人员的内容。带来的结果是：

• 更改令牌的值（静态文本、关联目标、资源路径或 var 值）不会改变英文哈希值，因此单纯修改值不会导致任何语言版本过时。
• 添加、删除或重新排序令牌****会改变哈希值，因此翻译内容会按预期重新进入暂存状态。
• 包含零个令牌的正文会像以前一样逐字节进行哈希处理，因此引入令牌不会导致大规模的重新过时现象。

系统指示翻译人员 %%n%% 标记是不可变的。必须恰好重现每个标记一次，绝不翻译或重新编号，并仅在语法需要时在句子内移动它们。收到翻译后，接收后检查会验证每个标记是否准确出现了一次，不匹配则判定该行失败以触发重试。存储的翻译正文保留标记并在读取时填充它们。

读取时替换

替换是一个读取路径关注点，与资源解析一样受控制。createScribe() 为应用运行时启用它，静态导出为 .md 布局启用它。CLI、scribe validate 和 Studio 保留原始令牌语法，以便它们能够自省并重新哈希源正文。

• 英文文档在原地替换其令牌，并针对默认语言环境进行解析。
• 翻译后的文档使用从当前英文正文中提取的令牌列表填充其 %%n%% 标记，并针对该文档的语言环境进行解析。因此，关联链接始终指向活动的本地化 slug，哪怕翻译本身已经是旧版本。

在运行时，有两种边缘情况会解析为空字符串（并被 scribe validate 标记）：目标类型在 :href 模式下没有 path 的关联，以及缺失的 var 键。

验证

scribe validate 会将以下情况报告为条目级问题：

• 令牌语法格式错误（错误的 JSON 字符串、参数数量错误、未知类型）：报错。
• relation：未知的 typeId、未知的 enSlug、缺少模式，或目标是非路由类型的 :href 关联：报错。
• asset：磁盘上缺失该文件：报错。
• var：文档的 vars 映射中缺少该键，或者 vars 不是一个键值对记录：报错。

在进行 MDX 正文验证之前，原始令牌会被屏蔽为惰性文本，因此有效的令牌永远不会产生虚假的 MDX 解析错误。

正文引用与删除

Studio 的“使用者 (Used by)”面板和资源浏览器会扫描正文内容：${{relation:...}} 令牌显示为反向引用（字段标签为 body），而 ${{asset:...}} 令牌注册为已声明的资源引用。删除仅在另一个条目的正文中被引用的条目绝不会级联、脱离或阻塞；请参阅条目删除。删除计划会在仅提示警告的“正文引用”部分列出此类引用。删除后，它们将成为悬空引用并导致验证错误。