将你的 Payload CMS 连接到本地化引擎后，选好要覆盖的 collections 和 globals，Lingo.dev 就会把其中已本地化的字段翻译到目标语言区域，并按对应语言区域写回 Payload。
适用于已启用本地化并使用 Lexical 富文本编辑器的 Payload 3 项目。暂不支持较旧的 Slate 编辑器。已本地化的 text、textarea 和 richText 字段会被翻译，文档中的其他内容都会保持不变。
Payload 集成按组织启用。如果你在 Settings -> Integrations 下没有看到它，联系我们，我们会帮你开启。
开始前请先准备#
你需要准备这三样：
- 已配置本地化的 Payload 3。 请确保源语言区域和目标语言区域与 Payload 配置中的语言区域保持一致。
- 一个带 API 密钥的服务用户。 在你的认证 collection（通常是
useAPIKey: true）上启用users，为 Lingo.dev 创建一个用户，并在 Payload 管理后台为其生成 API 密钥。该用户需要对你要翻译的每个 collection 和 global 拥有读取和更新权限。 - 一个本地化引擎。 它的术语表、品牌语气和规则会共同塑造翻译结果。
语言区域代码必须与 Payload 配置完全一致
你在 Lingo.dev 中选择的语言区域，必须与 localization.locales 下的代码完全一致。如果 Payload 里有 en 和 de，请选择 English 和 German，而不是 English (United States)：en-US 和 en 是不同的语言区域。请使用你的 Payload defaultLocale 作为源语言区域，因为插件会监听这个语言区域中的变更。
连接你的 Payload 实例#
打开集成
前往 Settings -> Integrations，然后在 Payload CMS 下点击 Connect。
输入实例信息
| 字段 | 填写内容 |
|---|---|
| 连接名称 | 例如 Production 或 Staging 这样的名称 |
| Payload 基础 URL | 你的实例根 URL，例如 https://cms.example.com。仅支持 HTTPS |
| 认证 Collection Slug | 服务 API 密钥所属的 collection，通常是 users |
| API 密钥 | 服务用户的 API 密钥 |
| 自定义请求头 | 可选。每次请求都会发送到你的实例 |
继续之前，Lingo.dev 会先用该密钥验证你的实例。
选择要翻译的内容
| 设置 | 作用 |
|---|---|
| Collections 和 Globals | 勾选要翻译的项。标记为 No read + update 的行会保持禁用，直到服务用户获得相应权限 |
| 源语言区域设置 | 编辑人员撰写内容所用的 locale。请使用你的 Payload defaultLocale |
| 目标语言区域设置 | 要翻译到的目标语言区域 |
| 引擎 | 用于翻译这部分内容的本地化引擎 |
| 翻译草稿保存 | 关闭时只翻译已发布的更改。开启后，草稿保存也会翻译，且译文会保留为草稿。 |
安装插件
最后一步会显示你的 webhook URL。请立即复制，它只会显示一次。 将它保存为 Payload 环境中的 LINGO_WEBHOOK_URL，然后安装插件并把它加入配置：
pnpm add @lingo.dev/payloadcmsimport { 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,
}),
],
});重新部署 Payload。此后，源语言区域中每次发布的变更都会发送到 Lingo.dev 进行翻译。
插件会做什么
它会新增一个 GET /api/lingo/schema 端点，用来告诉 Lingo.dev 哪些字段是已本地化的文本；同时还会添加一个 hook，在文档或 global 发生变化时通知 Lingo.dev。范围、语言区域和引擎都在控制台中管理，因此无需重新部署也能随时调整。省略 webhookUrl 则会跳过这个 hook，此后每次翻译都需要从控制台手动发起。
选择翻译范围#
连接页面包含三个标签页：Collections、Globals 和 Runs。
范围按 collection 和 global 分别设置。被选中的 collection 中，每个文档都会纳入范围。要修改范围、语言区域、引擎或草稿设置，请点击页面标题中的 Edit configuration。更改会在下一次运行时生效，无需重新部署。
在文档内部，是否会被翻译取决于你的 Payload 字段配置：
| 字段 | 是否翻译 |
|---|---|
标记为 text 的 textarea、richText 和 localized: true 字段 | 是 |
位于已本地化 group、array、blocks 或 tabs 内的相同字段类型 | 是 |
| 嵌入在富文本中的 blocks 和 inline blocks | 是的，它们的文本字段会按相同规则翻译 |
select、radio、checkbox、number、date、relationship、upload、json、code、email、point | 否 |
| 未本地化，且父级也未本地化的字段 | 否 |
id、blockType、blockName | 否 |
富文本会以 Lexical 树的形式进行翻译。格式、链接、上传内容和区块结构都会完整保留，只替换其中的文本。即使一句话被加粗文字或链接拆开，也会按一个完整句子来翻译。
如果要把某个字段纳入范围，请在 Payload 中将其标记为 localized: true，然后重新部署。下一次运行时就会自动识别。
同步与重新翻译#
自动运行。 在插件中设置好 webhookUrl 后，每次保存源语言环境中的文档或全局内容，都会通知 Lingo.dev。短时间内的多次保存会经过防抖处理，合并为一次运行。其他语言环境中的保存、草稿保存（除非已开启 Translate draft saves），以及不在你范围内的内容都会被忽略。
手动运行。 每个 collection、global 和文档行都有两个按钮：
| 按钮 | 作用 | 适用场景 |
|---|---|---|
| Sync | 只翻译自上次运行以来发生变化的内容 | 用于连接后补齐已有内容，或在失败后重试 |
| Retranslate | 从头重新翻译该行中的全部内容 | 适用于你修改引擎的术语表、品牌语气或规则之后 |
打开某个 collection 后，可以进入其中的文档并逐个同步。两个标签页都会显示每个项目的上次同步时间。
连接建立后不会自动翻译任何内容。要翻译现有内容，请在每个 collection 和 global 上点击 Sync。之后如果新增目标语言区域，处理方式也是一样：下一次 Sync 会将其补齐。
每个连接同一时间只会执行一个运行。后续请求会进入队列并依次开始。当某一行已被排队中或进行中的任务覆盖时，其按钮会显示为 Syncing...。
Retranslate 会覆盖手动修改
Retranslate 会重新生成其范围内的每个已翻译字段，包括团队已在 Payload 中手动修改过的译文。Sync 只会重新生成源文本自上次运行以来发生变化的字段，因此其他手动修改的内容会被保留。
查看 Run#
Runs 标签页会列出所有运行及其状态、触发方式（Webhook 或 Manual，同步或重新翻译）、开始时间和持续时长。排队中或运行中的任务都可以直接在列表中取消。
打开某次运行后，你可以查看它当前所处的阶段（从 Payload 读取、翻译、写回）、整体进度、各目标语言区域的进度，以及它覆盖的文档、collections 和 globals。每个项目都链接到 Payload 管理后台。
| 状态 | 含义 |
|---|---|
| 已排队 | 等待排在它前面的任务先完成 |
| 运行中 | 进行中 |
| 已完成 | 所有译文都已写回 |
| 已是最新 | 自上次运行以来，范围内没有任何内容发生变化。这不是失败 |
| 失败 | 该 run 已停止。原因会显示在 run 详情顶部 |
| 已取消 | 由你团队中的成员手动停止 |
运行失败时，已写入的内容会保留。错误信息会列出尚未写入的文档，下一次 Sync 会再次尝试写入这些文档。如果编辑者在运行过程中保存了某个文档，该文档会被跳过，并在下一次运行时补上。
译文会写到哪里#
每条翻译都会根据 Payload 自身的本地化模型，写入同一文档或 global 的目标语言区域版本中。只有已翻译的字段会被写入，其他所有字段都会保持不变。回写会以服务用户身份执行，且不会触发新一轮运行。
现有译文会被保留。文档首次同步时，目标语言区域中已有的内容会原样保留，只翻译缺失的字段。仍保留 Payload 默认值的字段会被视为缺失。需要替换现有译文时，请使用 Retranslate。
草稿与已发布#
当 Translate draft saves 关闭时（默认设置），只有已发布的更改才会触发一次运行，翻译内容也会在写入后立即发布。由于 Payload 发布的是整个文档，因此该文档中任何尚未发布的草稿编辑也会随翻译一并上线。
开启后，草稿保存也会触发运行。Lingo.dev 会读取源内容的最新草稿，并将每条译文作为草稿写入。在有人于 Payload 中发布这些译文之前，读者不会看到任何变化。适合在评估翻译质量时使用，或用于需要审核译文的流程中。
管理连接#
轮换 webhook URL#
打开连接页面标题栏中的菜单，选择 Regenerate webhook URL。旧 URL 会立即失效。更新 LINGO_WEBHOOK_URL 并重新部署。编辑该连接时，URL 会保持不变。
断开连接#
前往 Settings -> Integrations -> Payload CMS 断开连接。这会移除该连接、其运行历史，以及已翻译内容的记录。已经写入的译文仍会保留在 Payload 中。之后请从配置中移除 LINGO_WEBHOOK_URL 或该插件。
重新连接会生成新的 webhook URL
新连接会生成新的 webhook URL，因此在自动运行恢复之前，请先更新 LINGO_WEBHOOK_URL 并重新部署。第一次同步会重新读取范围内的每个文档，保留 Payload 中已有的译文，并补齐缺失内容。
限制#
| 限制项 | 说明 |
|---|---|
| Payload 版本 | 已配置本地化的 Payload 3 |
| 字段类型 | text、textarea 和 richText（仅限 Lexical）标记为 localized |
| 范围 | 整个 collection 和 global，不支持按字段选择 |
| 连接 | 每个组织可有多个，每个 Payload 实例一个 |
| 并发运行 | 每个连接一个 |
| Base URL | 仅支持 HTTPS |
故障排查#
连接失败并显示 "Payload rejected the API key"。 请检查密钥、认证 collection 的 slug，以及该 collection 是否已启用 useAPIKey。
某个 collection 或 global 显示 "No read + update"。 请在该 collection 的访问配置中为服务用户授予读取和更新权限，然后重新打开配置。
首次运行失败并显示 "The Lingo plugin isn't installed"。 请将 @lingo.dev/payloadcms 添加到你的 Payload 配置中的 plugins，然后重新部署。未安装插件也可以完成连接，但无法进行同步。
在 Payload 中发布后没有触发运行。 请检查是否已设置 LINGO_WEBHOOK_URL、是否已配置 localization、该 collection 或 global 是否在范围内、保存是否发生在源语言区域，以及这次操作是否为发布而非草稿。
字段不会被翻译。 该字段本身或其父级没有设置 localized: true，或者它不是 text、textarea 或 richText 字段。
连接显示 "Couldn't reach this Payload instance"。 请检查实例是否正常运行、密钥是否仍然有效，以及网关请求头是否依然可用。然后在 Settings -> Integrations 中更新该连接。
