Payload CMS 插件
提供 Payload 的本地化结构定义,在源内容变更时通知 Lingo.dev,同时保持编辑器原有的保存行为。
Lingo.dev 需要知道哪些 Payload 字段包含可本地化文本,以及源内容何时发生变更。@lingo.dev/payloadcms 提供两种对接方式:需通过身份验证的结构定义端点,以及可选的源内容变更通知。翻译内容的选择和回写通过 Payload 集成配置。
注册插件 #
在现有的 Payload 3 应用中安装:
npm install @lingo.dev/payloadcms@0.1.5将 lingo 添加到应用现有的插件列表中,并保留应用的本地化配置:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
localization: {
locales: ["en", "fr"],
defaultLocale: "en",
},
plugins: [lingo()],
});此处仅展示相关字段,并非可独立运行的完整 CMS 配置。请保留现有的集合、全局、数据库适配器、编辑器及其他必要设置。
该软件包导出 lingo 和 LingoPluginOptions。lingo() 返回一个 Payload 插件,唯一的配置选项是 webhookUrl?: string。注册时即使不提供该 URL,插件仍会提供结构定义端点,因此可以先配置结构发现,再配置自动通知。
通过 Payload 身份验证查看结构定义 #
插件会在 Payload 的 API 基础路径(通常为 /api/lingo/schema)下添加 GET /lingo/schema,并保留现有端点。请求一个已知的集合或全局:
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage请使用应用中的标识名。处理程序要求请求者为已通过身份验证的 Payload 用户;未通过身份验证的请求返回 401,实体缺失或未知时返回 404。集成使用已配置的 Payload 授权身份读取此端点。
响应会提取字段名称、类型、本地化标记、嵌套结构及相关的已解析默认值。其中包含受支持的嵌套分组、数组、区块、选项卡,以及定位文本所需的 Lexical 区块结构定义。无关的管理界面和编辑器配置会被省略,而不会将整个 Payload 配置序列化。
插件会解析参与本地化、面向内容作者的文本字段的默认值。受限或隐藏的默认值、结构性字段,以及无法解析或序列化的值,均不包含在默认值输出中。结构定义说明了集成可以检查哪些内容;获取结构定义并不会发起翻译请求。
源内容变更后通知集成 #
在 Lingo.dev 中连接 Payload 后,将获得的授权 URL 存入服务器配置,并传递给插件:
const webhookUrl = process.env.LINGO_PAYLOAD_WEBHOOK_URL;
if (!webhookUrl) throw new Error("Set LINGO_PAYLOAD_WEBHOOK_URL for automatic notifications");
const plugin = lingo({ webhookUrl });在现有的 plugins 数组中,用 plugin 替换 lingo()。环境变量名称由应用自行选择。该 URL 本身即可授权发送通知;请勿将其放入浏览器打包文件、提交的源代码或日志中。
同时配置 URL 和 localization.defaultLocale 后,插件会为集合和全局追加 afterChange 钩子,并保留现有钩子。集合通知会发送集合标识名、文档 ID 及可选的文档状态;全局通知会发送全局标识名。发送的数据仅为定位内容的引用,而非完整文档:集成会使用已配置的凭据重新读取内容。
明确指定在其他语言区域中进行的更改会被跳过,避免目标语言回写反复触发源内容翻译。未明确指定语言区域的更改则可能触发通知。请求的超时时间为五秒,传输失败会被忽略,确保编辑器可以完成保存。钩子也不会因 HTTP 状态表示失败而导致保存失败。
确认连接结果 #
首先验证集成能否使用其 Payload 凭据读取预期的结构定义。然后通过集成工作流进行一次经授权的源内容更改,并检查生成的目标语言区域内容。如果源内容已保存,但目标内容未生成,请检查通知是否被接受及翻译运行情况,而不要将编辑器保存成功视为通知已送达的证明。
在 Lingo.dev 的集成配置中选择集合、目标语言区域和本地化引擎。这些设置不属于插件选项,因此更改时无需替换应用中的插件注册配置。