Payload CMS plugin
Expose Payload's localization schema and notify Lingo.dev when source content changes, while preserving the editor's save behavior.
Lingo.dev needs to know which Payload fields contain localizable text and when their source content changes. @lingo.dev/payloadcms supplies those two connections: an authenticated schema endpoint and optional source-change notifications. Translation selection and writeback are configured through the Payload integration.
Register the plugin #
In an existing Payload 3 application, install:
npm install @lingo.dev/payloadcms@0.1.5Add lingo to the application's existing plugin list and keep its localization configuration:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
localization: {
locales: ["en", "fr"],
defaultLocale: "en",
},
plugins: [lingo()],
});This shows the relevant fields, not a complete standalone CMS configuration. Retain the existing collections, globals, database adapter, editor, and other required settings.
The package exports lingo and LingoPluginOptions. lingo() returns a Payload plugin, and its only option is webhookUrl?: string. Registering it without that URL still exposes the schema endpoint, so schema discovery can be configured before automatic notifications.
Inspect the schema through Payload authentication #
The plugin appends GET /lingo/schema relative to Payload's API base, normally /api/lingo/schema, while retaining existing endpoints. Request a known collection or global:
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepageUse slugs from your application. The handler requires an authenticated Payload user; an unauthenticated request returns 401, and a missing or unknown entity returns 404. The integration uses its configured Payload authority to read this endpoint.
The response projects field names, types, localization flags, nested structure, and relevant resolved defaults. It includes supported nested groups, arrays, blocks, tabs, and Lexical block schemas needed to locate text. It omits unrelated admin and editor configuration rather than serializing the entire Payload config.
Defaults are resolved for participating author-facing text fields. Restricted or hidden defaults, structural fields, and values that cannot be resolved or serialized are excluded from that default-value output. The schema describes what the integration can examine; fetching it does not request translation.
Notify the integration after a source change #
After connecting Payload in Lingo.dev, store the issued capability URL in server configuration and pass it to the plugin:
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 });Use plugin in the existing plugins array in place of lingo(). The environment-variable name is an application choice. The URL itself authorizes notifications; keep it out of browser bundles, committed source, and logs.
With both the URL and localization.defaultLocale configured, the plugin appends afterChange hooks to collections and globals, preserving existing hooks. A collection notification sends its slug, document ID, and optional document status. A global notification sends its slug. The payload is a pointer, not the full document: the integration rereads content using its configured credentials.
Changes explicitly made in another locale are skipped, which prevents target-language writeback from repeatedly starting source translation. A change without an explicit locale can notify. The request uses a five-second timeout, and transport failures are swallowed so an editor's save can complete. The hook also does not turn an unsuccessful HTTP status into a failed save.
Confirm the connection's result #
First verify that the integration can read the intended schema with its Payload credentials. Then make an authorized source change through the integration workflow and inspect the resulting target locale. If the source saves but no target arrives, check notification acceptance and the translation run rather than assuming the editor save proves delivery.
Choose collections, target locales, and the localization engine in Lingo.dev's integration configuration. Those settings are not plugin options, so they can change without replacing this application registration.