---
order: 6
section: features
title: 内联令牌 (Inline tokens)
description: 通过令牌在 MDX 正文中嵌入链接、资源 URL 和不可翻译的字符串，无需重新翻译即可更新所有语言版本。
noindex: false
canonicalPath: /zh-CN/docs/inline-tokens
---
MDX 正文通常需要使用 Scribe 已经知道的值，例如指向其他条目的链接、资源的公共 URL、绝对不能翻译的字面量，或者在多个地方重复使用的每个文档特有的小字符串。硬编码这些值会使正文变得脆弱（重命名的 slug 或移动的资源会悄悄地破坏链接），并污染翻译（URL 绝不应该被“翻译”）。

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

## 语法

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

| 令牌 | 解析为 | 
| --- | --- |
| `${{static:"text"}}` | 逐字字面量 `text`（一个 JSON 字符串，因此引号和转义符定义明确）。不被翻译，在所有语言环境中完全相同。 |
| `${{relation:<typeId>:<enSlug>:href}}` | 指向目标条目的**链接路径**（请参阅[关联模式](#relation-modes)）。模式后缀是必需的。 |
| `${{relation:<typeId>:<enSlug>:slug}}` | 目标的**英文 slug** 字符串，这是用于自己加载 Scribe 内容的 MDX 组件的稳定标识符。 |
| `${{asset:/web/path.webp}}` | 公共资源 URL（`assets.publicPath` 连接到路径）。请参阅[资源](/docs/assets)。 |
| `${{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>`，任何条目都可以声明它而**无需**将其添加到类型模式中：

```mdx
---
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:...}}` 令牌注册为已声明的资源引用。删除仅在另一个条目的**正文**中被引用的条目绝不会级联、脱离或阻塞；请参阅[条目删除](/docs/cli#scribe-delete)。删除计划会在仅提示警告的“正文引用”部分列出此类引用。删除后，它们将成为悬空引用并导致验证错误。