Payload CMS
Translate localized Payload 3 fields, preserve the resource structure, and choose how source changes reach target locales.
Payload already gives each localized field a place for its language versions. The Lingo.dev connection reads selected source fields, translates them through a localization engine, and writes the result into those same resources under the target locales. Collections, globals, and publication remain in Payload.
In the Studio 2.5 navigation, open Studio 2.5 → Integrations instead of Settings → Integrations. Existing connection and setup links still work.
Start with one resource and a manual Sync. After inspecting the result, add source-change notifications if translation should follow editing automatically.
Payload CMS integration comes with the Enterprise plan. See pricing for current availability. Settings → Integrations shows Not on your plan beside Payload when the organization needs plan access.
Prepare Payload and a service user #
Use Payload 3 with localization configured. Rich-text translation supports the Lexical editor; the older Slate editor is not supported. Your instance must be reachable by Lingo.dev over HTTPS.
Create a service user in an auth collection with useAPIKey: true, commonly users. Grant that user read and update access to every collection or global you intend to translate. Writes are attributed to this user. If a gateway requires additional headers, provide them when connecting and keep their values secret.
Match the connection's source locale to Payload's localization.defaultLocale, which the plugin watches for changes. Source and target codes must match Payload's configured codes exactly: en and en-US identify different locales. Choose an accessible localization engine in the connected Lingo.dev organization. If adding the connection is unavailable, check your organization's permissions and connection entitlement.
Connect the instance and expose its schema #
Open Settings → Integrations and select Connect for Payload CMS. Enter a connection name, the instance's root address, auth collection, service API key, and any gateway headers. Select Connect to verify access and save the connection. Keep the webhook URL shown afterward for automatic notifications.
Install the plugin in the Payload project:
pnpm add @lingo.dev/payloadcmsAdd lingo to the existing plugins array. This excerpt shows the plugin configuration; retain your project's collections, globals, localization, and other plugins:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
plugins: [
lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
],
});The plugin always registers GET /api/lingo/schema. Lingo.dev uses this endpoint to identify localized fields. You can create a connection before installing the plugin, but translation requires the schema endpoint.
For automatic notifications, copy the connection's webhook URL into Payload's LINGO_WEBHOOK_URL environment variable. Treat it as a secret capability: possession of the URL permits notification requests. Redeploy Payload after changing the plugin or environment. For manual-only translation, omit webhookUrl; the plugin will still expose the schema.
In Studio, select the instance under Connected, then select Set up. Choose its localization engine, source and target locales, and writeback mode. Select Continue, then choose the collections and globals to translate. The publication modes are described below.
Translate one resource #
Choose one collection or global containing a small localized text field and one target locale. Note its current source and target values in Payload before running Sync.
Select the mode according to the desired publication result:
| Mode | Source and writeback |
|---|---|
| Draft | Reads draft source content and writes translated fields as drafts for review in Payload. |
| Publish | Processes published changes and writes published translations. |
Payload keeps one shared draft per document and publishes it whole, so writing a translation into a published document with unpublished edits would publish those edits too. Publish mode therefore leaves such a document unchanged and reports its translation as failed. Publish the edits or revert to the published version in Payload, then run Sync again. To see those edits, the API key's user needs readVersions access to every version of the selected collections and globals; when that access is filtered, Publish mode leaves their published documents unchanged. A document that has never been published skips this check: Publish mode writes the translation into it, and it stays a draft. The check runs just before each write, so a draft saved during that moment can still be published with the translation: avoid saving drafts of documents while a sync writes them, and check their publication state afterward. Draft behavior also depends on your Payload configuration; verify the existing live version when testing an update.
Run Sync, open its workflow run, and inspect the actual target field in Payload. Check the wording, links, rich-text structure, locale, and publication state. Then read it through the consuming site. Connecting alone does not translate the catalog.
A first Sync keeps complete existing translations without replacing them. It fills missing fields, including fields whose current value only repeats the Payload default. If a field was retained, compare its value with that state before requesting replacement.
Select resources and fields #
The Collections and Globals tables have persistent Sync switches. Selecting a collection covers its documents; selecting a global covers that resource. Header actions process enabled resources. Where row-selection actions are offered, they queue that selected scope without redefining the connection's persistent selection.
Within those resources, the schema selects localized text, textarea, and Lexical richText fields. It also follows text inside localized groups, arrays, blocks, and tabs, including nested and inline rich-text blocks.
Nonlocalized fields and structural values such as id, blockType, and blockName stay outside translation text. Selects, numbers, relationships, uploads, code, and arbitrary JSON do not become translatable because their collection is selected. To include another text field, configure its localization in Payload and redeploy.
Lexical processing keeps sentence context across inline formatting and links, then reconstructs the tree with its links, media, and blocks. Test a representative document before expanding scope, particularly if your project uses custom fields or editor extensions.
Keep translations aligned with source changes #
With a webhook URL and a default locale configured, the plugin sends notifications after source-locale changes. A notification contains a resource pointer, not the document body. Lingo.dev rereads the content using the stored service credentials, applies the connection's scope and mode, and groups nearby notifications before processing them.
Target-locale writes do not trigger another translation. Notification failures also do not fail an editor's save, so a successful save alone cannot confirm delivery. If a change was missed, inspect the run history and use manual Sync to reconcile the content. Draft saves are relevant in Draft mode; a target-locale save or an out-of-scope resource is not a source change for this connection.
Use Sync for changed source and missing target content. It compares content with the available baseline. When an earlier source artifact is unavailable, recovery can regenerate the affected content, so inspect the diff rather than assuming every manual edit will remain. After adding a target locale, run Sync to fill it.
Use Retranslate when you intend to replace the selected translations, including hand-edited fields. For example, a major change to the localization engine's instructions may justify new output even when the source is unchanged. Requests queue behind the active connection run; submitting the same action repeatedly does not make it finish sooner.
Recover a changed or partially written document #
The writeback step rereads source content. If an editor changed it after planning, the document is skipped instead of applying translated values to a different revision or array order. A later Sync reconciles the new source.
Failed or cancelled runs retain successful writes. In Workflow runs, distinguish completed, up-to-date, skipped, failed, and cancelled work, and inspect the affected resources before retrying. Stop cancels active work where available; it does not roll back fields already written. An up-to-date outcome means there was no selected change to process.
If output never appears, check the schema endpoint, field localization and type, service-user read/update permissions, exact locale code, resource Sync selection, mode, and webhook environment. Correct an unreachable instance or rejected key before requesting retranslation.
Change settings or disconnect #
Change resource selection, locales, localization engine, and mode in Studio. Rename the connection or manage its credentials in Settings → Integrations. These changes keep its webhook URL.
To rotate the API key, open the connection in Settings → Integrations and select Replace key. Enter a key from the same auth collection and re-enter every custom header the instance still needs; the supplied headers replace the stored ones.
Changing the instance address requires a new connection. Set up its translation scope and update Payload's environment with the new webhook URL before relying on automatic notifications again.
Disconnect removes the connection's local history and sync state and stops future reads and writes. Existing translated content stays in Payload. Remove the old webhook environment value or hook, and revoke the service key separately if it is no longer needed.
A new connection establishes a new baseline. Its first Sync retains eligible existing translations and fills gaps; it does not restore a previous connection's local run history. Inspect that first run as you would any new connection.