Payload CMS

翻译 Payload 3 中已启用本地化的字段,保留资源结构,并选择源内容更改同步到目标语言区域的方式。

Payload 已为每个本地化字段的各语言版本预留了位置。Lingo.dev 连接会读取所选源字段,通过本地化引擎翻译,再将结果写回同一资源的目标语言区域。集合、全局资源和发布仍由 Payload 管理。

在 Studio 2.5 导航中,请打开 Studio 2.5 → 集成,而不是 设置 → 集成。现有的连接和设置链接仍可正常使用。

先从一个资源开始,手动执行一次同步。检查结果后,如果希望翻译随编辑自动更新,再启用源内容更改通知。

Payload CMS 集成需使用 Enterprise 方案。请参阅定价了解当前可用情况。如果组织需要获得相应方案的访问权限,设置 → 集成中会在 Payload 旁显示当前方案不支持。

准备 Payload 和服务用户 #

请使用已配置本地化的 Payload 3。富文本翻译支持 Lexical 编辑器,不支持旧版 Slate 编辑器。您的实例必须能通过 HTTPS 被 Lingo.dev 访问。

在配置了 useAPIKey: true 的身份验证集合中创建服务用户,该集合通常为 users。授予该用户对所有待翻译集合或全局资源的读取和更新权限。写入操作会记在此用户名下。如果网关需要额外标头,请在连接时提供,并妥善保密其值。

将连接的源语言区域设为 Payload 的 localization.defaultLocale,插件会监测该语言区域的更改。源和目标语言区域代码必须与 Payload 配置的代码完全一致:en 和 en-US 表示不同的语言区域。在已连接的 Lingo.dev 组织中选择一个可访问的本地化引擎。如果无法添加连接,请检查您的组织权限,以及组织是否有权使用连接功能。

连接实例并提供架构访问 #

打开设置 → 集成,选择 Payload CMS 的连接。输入连接名称、实例根地址、身份验证集合、服务 API 密钥,以及所需的网关标头。选择连接,验证访问并保存连接。保存随后显示的 webhook URL,以便用于自动通知。

在 Payload 项目中安装插件:

bash
pnpm add @lingo.dev/payloadcms

将 lingo 添加到现有的 plugins 数组中。此片段仅展示插件配置;请保留项目中的集合、全局资源、本地化配置和其他插件:

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

export default buildConfig({
  plugins: [
    lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
  ],
});

插件始终会注册 GET /api/lingo/schema。Lingo.dev 通过此端点识别本地化字段。您可以在安装插件前创建连接,但必须提供架构端点才能进行翻译。

如需自动通知,请将连接的 webhook URL 复制到 Payload 的 LINGO_WEBHOOK_URL 环境变量中。请将其视为需要保密的访问凭证:持有该 URL 即可发送通知请求。更改插件或环境配置后,请重新部署 Payload。如果只需手动翻译,可省略 webhookUrl;插件仍会提供架构访问。

在 Studio 中,从已连接下选择实例,再选择设置。选择本地化引擎、源和目标语言区域,以及回写模式。选择继续,然后选择要翻译的集合和全局资源。各发布模式的说明见下文。

翻译一个资源 #

选择一个包含简短本地化文本字段的集合或全局资源,并选择一个目标语言区域。运行同步前,记下该字段在 Payload 中当前的源值和目标值。

根据期望的发布结果选择模式:

模式源内容与回写
草稿读取源内容草稿,将翻译后的字段以草稿形式写入,供您在 Payload 中审核。
发布处理已发布的更改,并写入已发布的译文。

Payload 为每个文档保留一份共享草稿,发布时会发布整份草稿。因此,向已有未发布修改的已发布文档写入译文时,这些修改也会一并发布。为避免这种情况,发布模式会保持此类文档不变,并将其翻译标记为失败。请先在 Payload 中发布这些修改,或将文档还原为已发布版本,然后重新运行同步。要查看这些修改,API 密钥对应的用户必须对所选集合和全局的所有版本拥有 readVersions 访问权限;如果该权限受到筛选限制,发布模式会保持其中的已发布文档不变。从未发布过的文档会跳过此检查:发布模式会将译文写入文档,但文档仍保持草稿状态。检查会在每次写入前执行,因此,在检查与写入之间保存的草稿仍可能随译文一并发布。同步正在向文档写入内容时,请勿保存这些文档的草稿,并在同步后检查其发布状态。草稿的处理方式还取决于您的 Payload 配置;测试更新时,请核查当前已上线的版本。

运行同步,打开对应的工作流运行,并检查 Payload 中实际写入的目标字段。核对措辞、链接、富文本结构、语言区域和发布状态,再到使用该内容的网站上查看结果。仅建立连接并不会翻译内容目录。

首次同步会保留完整的现有译文,不会将其替换。同步会补齐缺失字段,包括当前值仅与 Payload 默认值相同的字段。如果某个字段被保留,请先将其值与同步前的状态进行比较,再请求替换。

选择资源和字段 #

集合和全局表格中的同步开关会持续保存选择。选中集合会涵盖其中的文档;选中全局资源会涵盖该资源。表头操作会处理已启用的资源。如果表格提供行选择操作,这些操作会将所选范围加入队列,但不会更改连接中持续保存的选择。

在这些资源中,架构会选取已启用本地化的 text、textarea 和 Lexical richText 字段。它还会查找本地化组、数组、区块和选项卡中的文本,包括嵌套和内联富文本区块中的文本。

未启用本地化的字段,以及 id、blockType 和 blockName 等结构值,不会纳入翻译文本。选择项、数字、关联、上传内容、代码和任意 JSON,不会仅因所属集合被选中就变得可翻译。要纳入其他文本字段,请在 Payload 中为其配置本地化,再重新部署。

处理 Lexical 内容时,会保留跨内联格式和链接的句子上下文,再重建包含链接、媒体和区块的树结构。扩大翻译范围前,请先测试一份有代表性的文档,尤其是项目使用了自定义字段或编辑器扩展时。

让译文与源内容更改保持同步 #

配置 webhook URL 和默认语言区域后,插件会在源语言区域内容更改后发送通知。通知仅包含资源指针,不包含文档正文。Lingo.dev 会使用已存储的服务凭证重新读取内容,按连接的范围和模式处理,并在处理前合并时间相近的通知。

写入目标语言区域不会触发新的翻译。通知失败也不会导致编辑者的保存操作失败,因此仅凭保存成功,无法确认通知已送达。如果遗漏了某次更改,请检查运行历史,并手动同步以使内容保持一致。在草稿模式下,保存草稿会被纳入处理;保存目标语言区域内容或范围外的资源,则不属于此连接的源内容更改。

使用同步处理已更改的源内容和缺失的目标内容。同步会将内容与可用基线进行比较。如果无法获取较早的源内容产物,恢复过程可能会重新生成受影响的内容,因此请检查差异,不要假定所有手动修改都会保留。添加目标语言区域后,请运行同步,补齐该语言区域的内容。

如果您希望替换所选译文,包括手动编辑过的字段,请使用重新翻译。例如,本地化引擎的指令发生重大更改后,即使源内容未变,也可能需要生成新的译文。请求会排在当前正在执行的连接运行之后;重复提交同一操作并不会让它更快完成。

恢复已更改或部分写入的文档 #

回写步骤会重新读取源内容。如果编辑者在规划完成后修改了内容,系统会跳过该文档,而不会将译文写入不同的修订版本或数组顺序。后续同步会使译文与新的源内容保持一致。

运行失败或取消后,成功写入的内容仍会保留。在工作流运行中,请区分已完成、已是最新、已跳过、失败和已取消的任务,并在重试前检查受影响的资源。如果提供了停止操作,可用它取消正在进行的任务,但不会回滚已写入的字段。“已是最新”表示所选范围内没有需要处理的更改。

如果始终没有输出,请检查架构端点、字段的本地化配置和类型、服务用户的读取及更新权限、语言区域代码是否完全一致、资源的同步选择、模式,以及 webhook 环境配置。请求重新翻译前,请先解决实例无法访问或密钥被拒绝的问题。

更改设置或断开连接 #

在 Studio 中更改资源选择、语言区域、本地化引擎和模式。在设置 → 集成中重命名连接或管理凭证。这些更改不会改变连接的 webhook URL。

要轮换 API 密钥,请在设置 → 集成中打开连接,选择替换密钥。输入来自同一身份验证集合的密钥,并重新输入实例仍需使用的所有自定义标头;新提供的标头会替换已存储的标头。

更改实例地址需要创建新连接。请先设置新连接的翻译范围,并用新的 webhook URL 更新 Payload 的环境配置,再恢复使用自动通知。

断开连接会移除该连接的本地历史和同步状态,并停止后续读取和写入。现有译文仍会保留在 Payload 中。请移除旧的 webhook 环境变量值或钩子;如果服务密钥已不再需要,请另行撤销。

新连接会建立新的基线。首次同步会保留符合条件的现有译文并补齐缺失内容,但不会恢复上一连接的本地运行历史。请像检查其他新连接一样,检查这次首次运行。