Payload CMS

将你的 Payload CMS 连接到本地化引擎后，选好要覆盖的 collections 和 globals，Lingo.dev 就会把其中已本地化的字段翻译到目标语言区域，并按对应语言区域写回 Payload。

适用于已启用本地化并使用 Lexical 富文本编辑器的 Payload 3 项目。暂不支持较旧的 Slate 编辑器。已本地化的 text、textarea 和 richText 字段会被翻译，文档中的其他内容都会保持不变。

Payload CMS 包含在 Enterprise 方案中。如果 Connect 页面显示 Payload CMS is not on your plan，请联系我们，我们会帮您处理。

开始前请先准备#

你需要准备这三样：

• 已配置本地化的 Payload 3。 请确保源语言区域和目标语言区域与 Payload 配置中的语言区域保持一致。
• 一个带 API 密钥的服务用户。 在你的认证 collection（通常是 useAPIKey: true）上启用 users，为 Lingo.dev 创建一个用户，并在 Payload 管理后台为其生成 API 密钥。该用户需要对你要翻译的每个 collection 和 global 拥有读取和更新权限。
• 一个本地化引擎。 它的术语表、品牌语气和规则会共同塑造翻译结果。

连接你的 Payload 实例#

pnpm add @lingo.dev/payloadcms

import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";

export default buildConfig({
  // ...your collections, globals, and localization config
  plugins: [
    lingo({
      webhookUrl: process.env.LINGO_WEBHOOK_URL,
    }),
  ],
});

选择翻译范围#

连接页面有四个标签页：Collections、Globals、Workflow runs 和 Settings。

范围会按 collection 和 global 分别设置。Collections 和 Globals 标签页会列出您的实例提供的全部内容，每项占一行，并显示上次同步时间。每行都有一个 Sync 开关：打开后，该 collection 中的所有文档或该 global 都会从此纳入范围。切换开关后，更改会立即保存，并在下一次运行时生效，无需重新部署。表头中的开关可一次性为列表中的所有项打开或关闭 Sync。

标记为 no read + update 的行会被锁定：服务用户无法读取和更新它，因此无法翻译。标记为 not localized yet 的行表示 Sync 处于关闭状态。

语言区域设置、引擎和模式可在 Settings 标签页中更改。

在文档内部，是否会被翻译取决于你的 Payload 字段配置：

富文本会以 Lexical 树的形式进行翻译。格式、链接、上传内容和区块结构都会完整保留，只替换其中的文本。即使一句话被加粗文字或链接拆开，也会按一个完整句子来翻译。

如果要把某个字段纳入范围，请在 Payload 中将其标记为 localized: true，然后重新部署。下一次运行时就会自动识别。

同步与重新翻译#

自动运行。 在插件中设置 webhookUrl 后，只要在源语言区域设置中保存文档或 global，Lingo.dev 就会收到通知。短时间内的多次保存会去抖合并为一次运行。其他语言区域设置中的保存、草稿保存（除非连接处于 Draft 模式），以及不在范围内的内容都会被忽略。

手动运行。 两个按钮，对应两种不同的任务：

这两个按钮都位于页面顶部，作用于所有已开启 Sync 的内容。从页面顶部执行 Retranslate 时，系统会先要求您确认。若只想运行部分 collections 或 globals，可勾选对应行：随后会出现 Queue sync (N) 和 Queue retranslation (N)，且只作用于这些行。只有当某一行的 Sync 开关已打开时，才能勾选该行。

连接建立时不会自动翻译任何内容。若要翻译已有内容，请点击页面顶部的 Sync。之后新增目标语言区域设置时也是一样：下一次 Sync 会补齐翻译。

每个连接同一时间只能有一个任务在运行。后续请求会进入队列，并按顺序开始。

查看 Run#

Workflow runs 标签页会列出每一次运行：开始时间、触发方式（Webhook 或 Manual，然后是 Sync 或 Retranslate）、覆盖的语言区域设置、耗时以及状态。排队中或运行中的任务会显示 Stop 按钮。展开某一行可按语言区域设置查看结果。

运行失败时，已写入的内容会保留。错误信息会列出尚未写入的文档，下一次 Sync 会再次尝试写入这些文档。如果编辑者在运行过程中保存了某个文档，该文档会被跳过，并在下一次运行时补上。

译文会写到哪里#

每条翻译都会根据 Payload 自身的本地化模型，写入同一文档或 global 的目标语言区域版本中。只有已翻译的字段会被写入，其他所有字段都会保持不变。回写会以服务用户身份执行，且不会触发新一轮运行。

现有译文会被保留。文档首次同步时，目标语言区域中已有的内容会原样保留，只翻译缺失的字段。仍保留 Payload 默认值的字段会被视为缺失。需要替换现有译文时，请使用 Retranslate。

草稿与已发布#

在 Publish 模式下，只有已发布的更改才会触发运行，且译文会在写入后立即发布。Payload 会发布整个文档，因此该文档中所有尚未发布的草稿修改也会随译文一并上线。

在 Draft 模式下，草稿保存也会触发运行。Lingo.dev 会读取源内容的最新草稿，并将每个译文写为草稿。在有人于 Payload 中发布译文之前，读者不会看到任何变化。评估翻译质量或译文需要经过审核时，可使用此模式。

您之后也可以在 Settings 标签页中更改模式。

管理连接#

设置#

Settings 标签页会显示该连接读取的是哪个实例、哪些 collections 和 globals 已开启 Sync，以及连接当前是 Working 还是 Cannot be reached。您可以在这里更改名称、源语言区域设置、目标语言区域设置、引擎和模式。每次更改都会保留 webhook URL，因此无需重新部署。

地址和 API 密钥会在创建连接时设定，之后无法更改。若要让 Lingo.dev 指向其他地址或密钥，请先断开连接，再重新连接。

断开连接#

Settings 标签页底部的 Disconnect 会停止 Lingo.dev 对该实例的读取和写入。这会移除该连接、其运行历史以及已翻译内容的记录。已写入 Payload 的译文会保留。之后请从配置中移除 LINGO_WEBHOOK_URL 或插件。

限制#

故障排查#

连接失败并显示 "Payload rejected the API key"。 请检查密钥、认证 collection 的 slug，以及该 collection 是否已启用 useAPIKey。

某个 collection 或 global 显示 "no read + update"。 请在该 collection 的访问配置中为服务用户授予读取和更新权限，然后重新加载连接页面。该行的 Sync 开关就会解锁。

首次运行失败并显示 "The Lingo plugin isn't installed"。 请将 @lingo.dev/payloadcms 添加到你的 Payload 配置中的 plugins，然后重新部署。未安装插件也可以完成连接，但无法进行同步。

在 Payload 中发布后没有触发运行。 请检查是否已设置 LINGO_WEBHOOK_URL、是否已配置 localization、该 collection 或 global 是否在范围内、此次保存是否发生在源语言区域设置中，以及这次操作是发布而不是草稿，除非连接处于 Draft 模式。

字段不会被翻译。 该字段本身或其父级没有设置 localized: true，或者它不是 text、textarea 或 richText 字段。

Settings 标签页将连接显示为 Cannot be reached。请检查实例是否正在运行、密钥是否仍然有效，以及所有网关请求头是否仍能正常工作。现有连接的地址和密钥无法编辑，因此如果其中任一项已变更，请断开连接后重新连接，并用新的 webhook URL 更新 LINGO_WEBHOOK_URL。

下一步#