Verbinde dein Payload CMS mit einer Lokalisierungs-Engine, wähle die Collections und Globals aus, die abgedeckt werden sollen, und Lingo.dev übersetzt die lokalisierten Felder in deine Zielsprachen und schreibt sie in Payload unter der jeweiligen Sprache zurück.
Funktioniert mit Payload-3-Projekten, in denen die Lokalisierung aktiviert ist und der Lexical-Rich-Text-Editor verwendet wird. Der ältere Slate-Editor wird nicht unterstützt. Lokalisierte text-, textarea- und richText-Felder werden übersetzt. Alles andere im Dokument bleibt unverändert.
Die Payload-Integration wird pro Organisation aktiviert. Wenn du sie unter Settings -> Integrations nicht siehst, melde dich bei uns – wir schalten sie für dich frei.
Bevor du loslegst#
Du brauchst drei Dinge:
- Payload 3 mit eingerichteter Lokalisierung. Achte darauf, dass deine Quell- und Ziel-Sprachen mit den Sprachen in deiner Payload-Konfiguration übereinstimmen.
- Ein Service-Benutzer mit API-Schlüssel. Aktiviere
useAPIKey: truefür deine Auth-Collection (normalerweiseusers), erstelle einen Benutzer für Lingo.dev und generiere im Payload-Admin einen API-Schlüssel dafür. Der Benutzer braucht Lese- und Aktualisierungszugriff auf jede Collection und jedes Global, die du übersetzen möchtest. - Eine Lokalisierungs-Engine. Ihr Glossar, ihre Markenstimme und ihre Regeln prägen die Übersetzungen.
Sprachcodes müssen zu deiner Payload-Konfiguration passen
Die Sprachen, die du in Lingo.dev auswählst, müssen exakt mit den Codes unter localization.locales übereinstimmen. Wenn Payload en und de verwendet, wähle Englisch und Deutsch, nicht Englisch (Vereinigte Staaten): en-US und en sind unterschiedliche Sprachen. Verwende deine Payload-defaultLocale als Ausgangssprache, denn auf Änderungen in dieser Sprache reagiert das Plugin.
Verbinde deine Payload-Instanz#
Öffne die Integration
Gehe zu Settings -> Integrations und klicke bei Payload CMS auf Connect.
Gib die Details deiner Instanz ein
| Feld | Was du eintragen musst |
|---|---|
| Verbindungsname | Eine Bezeichnung wie Production oder Staging |
| Payload Base URL | Die Root-URL deiner Instanz, z. B. https://cms.example.com. Nur HTTPS |
| Auth Collection Slug | Die Collection, zu der dein Service-API-Schlüssel gehört, normalerweise users |
| API Key | Der API-Schlüssel des Service-Benutzers |
| Custom headers | Optional. Wird mit jeder Anfrage an deine Instanz gesendet. |
Lingo.dev prüft den Schlüssel gegen deine Instanz, bevor es weitergeht.
Wähle aus, was übersetzt werden soll
| Einstellung | Was sie macht |
|---|---|
| Collections and Globals | Aktiviere die Einträge, die übersetzt werden sollen. Eine Zeile mit No read + update bleibt deaktiviert, bis der Service-User Zugriff darauf hat |
| Source Locale | Die Sprache, in der dein Redaktionsteam schreibt. Verwende dein Payload-defaultLocale |
| Target Locales | Die Sprachen, in die übersetzt werden soll |
| Engine | Die Lokalisierungs-Engine, die diese Inhalte übersetzt |
| Translate draft saves | Aus übersetzt nur veröffentlichte Änderungen. Ein übersetzt auch gespeicherte Entwürfe und belässt die Übersetzungen als Entwürfe |
Installiere das Plugin
Im letzten Schritt wird dir deine Webhook-URL angezeigt. Kopiere sie jetzt. Sie wird nur einmal angezeigt. Speichere sie als LINGO_WEBHOOK_URL in deiner Payload-Umgebung, installiere dann das Plugin und füge es deiner Konfiguration hinzu:
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,
}),
],
});Deploye Payload erneut. Ab jetzt wird jede in der Ausgangssprache veröffentlichte Änderung zur Übersetzung an Lingo.dev gesendet.
Was das Plugin macht
Es fügt einen GET /api/lingo/schema-Endpunkt hinzu, der Lingo.dev mitteilt, welche deiner Felder lokalisierter Text sind, sowie einen Hook, der Lingo.dev benachrichtigt, wenn sich ein Dokument oder Global ändert. Umfang, Sprachen und Engine verwaltest du im Dashboard, sodass du sie ohne erneutes Deployment ändern kannst. Lass webhookUrl weg, um den Hook zu überspringen und jede Übersetzung über das Dashboard zu starten.
Wähle aus, was übersetzt wird#
Die Verbindungsseite hat drei Tabs: Collections, Globals und Runs.
Der Umfang wird pro Collection und pro Global festgelegt. Jedes Dokument in einer ausgewählten Collection ist eingeschlossen. Um Umfang, Sprachen, Engine oder die Entwurfs-Einstellung zu ändern, klicke im Seitenkopf auf Konfiguration bearbeiten. Die Änderungen gelten für den nächsten Lauf, ganz ohne erneutes Deployment.
Innerhalb eines Dokuments entscheidet deine Payload-Feldkonfiguration, was übersetzt wird:
| Feld | Übersetzt |
|---|---|
text-, textarea- und richText-Felder, die mit localized: true markiert sind. | Ja |
Dieselben Feldtypen innerhalb eines lokalisierten group, array, blocks oder tabs | Ja |
| Blöcke und Inline-Blöcke in Rich Text | Ja, ihre Textfelder nach denselben Regeln |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | Nein |
| Felder, die nicht lokalisiert sind und kein lokalisiertes übergeordnetes Feld haben. | Nein |
id, blockType, blockName | Nein |
Rich Text wird als Lexical-Baum übersetzt. Formatierung, Links, Uploads und Blockstruktur bleiben erhalten, und nur der enthaltene Text wird ersetzt. Ein Satz, der durch fett formatierten Text oder einen Link unterbrochen ist, wird als zusammenhängender Satz übersetzt.
Um ein Feld in den Umfang aufzunehmen, markiere es in Payload mit localized: true und deploye erneut. Beim nächsten Lauf wird es automatisch berücksichtigt.
Synchronisieren und neu übersetzen#
Automatische Ausführungen. Ist webhookUrl im Plugin eingerichtet, benachrichtigt jedes Speichern eines Dokuments oder globalen Inhalts in der Quellsprache Lingo.dev. Mehrere Speicherungen innerhalb eines kurzen Zeitfensters werden zu einer einzigen Ausführung gebündelt. Speicherungen in anderen Sprachen, Entwurfsspeicherungen (es sei denn, Entwurfsspeicherungen übersetzen ist aktiviert) und Inhalte außerhalb Ihres Geltungsbereichs werden ignoriert.
Manuelle Läufe. Jede Collection-, Global- und Dokumentzeile hat zwei Schaltflächen:
| Button | Was sie macht | Wann du ihn verwendest |
|---|---|---|
| Sync | Übersetzt nur das, was sich seit dem letzten Lauf geändert hat | Zum Nachziehen von Inhalten nach dem Verbinden oder für einen neuen Versuch nach einem Fehler |
| Retranslate | Übersetzt alles in der Zeile erneut, von Grund auf | Nach Änderungen am Glossar, an der Markenstimme oder an den Regeln deiner Engine |
Öffne eine Collection, um zu ihren Dokumenten zu gelangen und sie einzeln zu synchronisieren. Beide Tabs zeigen dir, wann jedes Element zuletzt synchronisiert wurde.
Beim Verbinden wird nichts übersetzt. Wenn du bereits vorhandene Inhalte übersetzen möchtest, klicke bei jeder Collection und jedem Global auf Sync. Wenn du später eine weitere Zielsprache hinzufügst, funktioniert es genauso: Der nächste Sync ergänzt sie.
Pro Verbindung kann immer nur ein Lauf gleichzeitig ausgeführt werden. Weitere Anfragen landen in der Warteschlange und starten der Reihe nach. Während eine Zeile von einem wartenden oder laufenden Lauf erfasst ist, steht auf ihren Schaltflächen Syncing....
Retranslate überschreibt manuelle Bearbeitungen
Retranslate erstellt jedes übersetzte Feld in seinem Umfang neu, einschließlich Übersetzungen, die dein Team in Payload manuell bearbeitet hat. Sync erstellt nur Felder neu, deren Ausgangstext sich geändert hat, sodass manuelle Änderungen an anderen Stellen erhalten bleiben.
Einen Lauf verfolgen#
Im Tab Runs siehst du jeden Lauf mit Status, Auslöser (Webhook oder Manual, Sync oder Retranslate), Startzeit und Dauer. Einen wartenden oder laufenden Lauf kannst du direkt aus der Liste abbrechen.
Öffne einen Lauf, um zu sehen, in welcher Phase er sich befindet (Lesen aus Payload, Übersetzen, Zurückschreiben), wie weit er insgesamt ist, den Fortschritt pro Zielsprache sowie die Dokumente, Collections und Globals, die er abdeckt. Jedes Element verlinkt zum Payload-Admin.
| Status | Bedeutung |
|---|---|
| Queued | Wartet auf den Lauf davor |
| Running | In Bearbeitung |
| Completed | Jede Übersetzung wurde zurückgeschrieben |
| Up to date | Seit dem letzten Lauf hat sich nichts innerhalb des Umfangs geändert. Kein Fehler |
| Failed | Der Lauf wurde gestoppt. Der Grund steht oben in den Laufdetails |
| Cancelled | Von jemandem aus deinem Team gestoppt |
Ein fehlgeschlagener Durchlauf behält alles bei, was bereits geschrieben wurde. Die Fehlermeldung listet die Dokumente auf, die nicht geschrieben wurden, und bei der nächsten Synchronisierung wird erneut versucht, sie zu schreiben. Ein Dokument, das während des Durchlaufs von einer Editorin oder einem Editor gespeichert wurde, wird übersprungen und im nächsten Durchlauf berücksichtigt.
Wo Übersetzungen landen#
Jede Übersetzung wird im selben Dokument oder Global unter ihrer Zielsprache gespeichert – nach Payloads eigenem Lokalisierungsmodell. Es werden nur übersetzte Felder geschrieben. Alle anderen Felder bleiben unverändert. Rückschreibungen laufen über den Service-Benutzer und lösen keinen neuen Durchlauf aus.
Vorhandene Übersetzungen bleiben erhalten. Beim ersten Sync eines Dokuments bleibt alles, was in einer Zielsprache bereits vorhanden ist, an Ort und Stelle, und nur die fehlenden Felder werden übersetzt. Ein Feld, das noch den Payload-Standardwert enthält, gilt als fehlend. Verwende Retranslate, um vorhandene Übersetzungen zu ersetzen.
Entwürfe vs. veröffentlicht#
Ist Entwurfsspeicherungen übersetzen deaktiviert (standardmäßig), lösen nur veröffentlichte Änderungen einen Durchlauf aus, und Übersetzungen werden sofort veröffentlicht, sobald sie geschrieben sind. Payload veröffentlicht immer das gesamte Dokument. Dadurch gehen alle unveröffentlichten Entwurfsänderungen darin zusammen mit der Übersetzung live.
Wenn die Option aktiviert ist, starten auch Entwurfs-Speicherungen Läufe. Lingo.dev liest den neuesten Entwurf der Quelle und schreibt jede Übersetzung als Entwurf. Für deine Leserinnen und Leser ändert sich nichts, bis jemand die Übersetzung in Payload veröffentlicht. Nutze das, wenn du die Übersetzungsqualität bewertest oder Übersetzungen durch eine Prüfung gehen.
Verbindung verwalten#
Webhook-URL erneuern#
Öffnen Sie das Menü in der Kopfzeile der Verbindungsseite und wählen Sie Webhook-URL neu generieren. Die alte URL funktioniert sofort nicht mehr. Aktualisieren Sie LINGO_WEBHOOK_URL und deployen Sie neu. Wenn Sie die Verbindung bearbeiten, bleibt die URL erhalten.
Verbindung trennen#
Trenne die Verbindung unter Settings -> Integrations -> Payload CMS. Dadurch werden die Verbindung, ihr Laufverlauf und der Eintrag darüber entfernt, was bereits übersetzt wurde. Bereits geschriebene Übersetzungen bleiben in Payload erhalten. Entferne danach LINGO_WEBHOOK_URL oder das Plugin aus deiner Konfiguration.
Erneut verbinden heißt: neue Webhook-URL
Eine neue Verbindung erhält eine neue Webhook-URL. Aktualisiere deshalb LINGO_WEBHOOK_URL und deploye erneut, bevor automatische Läufe wieder funktionieren. Der erste Sync liest jedes Dokument im Umfang erneut ein, behält die Übersetzungen bei, die in Payload bereits vorhanden sind, und füllt die Lücken.
Einschränkungen#
| Einschränkung | Details |
|---|---|
| Payload-Version | Payload 3 mit konfigurierter Lokalisierung |
| Feldtypen | text-, textarea- und richText-Felder (nur Lexical), die mit localized markiert sind. |
| Umfang | Komplette Collections und Globals. Keine Auswahl auf Feldebene |
| Verbindungen | Mehrere pro Organisation, eine pro Payload-Instanz |
| Gleichzeitige Läufe | Eine pro Verbindung |
| Basis-URL | Nur HTTPS |
Fehlerbehebung#
Das Verbinden schlägt mit "Payload rejected the API key" fehl. Prüfe den Schlüssel, den Slug der Auth-Collection und ob useAPIKey für diese Collection aktiviert ist.
Eine Collection oder ein Global zeigt "No read + update" an. Gib dem Service-Benutzer in der Zugriffskonfiguration dieser Collection Lese- und Aktualisierungszugriff und öffne dann die Konfiguration erneut.
Der erste Lauf schlägt mit "The Lingo plugin isn't installed" fehl. Füge @lingo.dev/payloadcms zu plugins in deiner Payload-Konfiguration hinzu und deploye erneut. Das Verbinden funktioniert ohne das Plugin, das Synchronisieren jedoch nicht.
Das Veröffentlichen in Payload startet keinen Lauf. Prüfe, ob LINGO_WEBHOOK_URL gesetzt ist, localization konfiguriert ist, die Collection oder das Global im Umfang liegt, die Speicherung in der Ausgangssprache erfolgt ist und ob es eine Veröffentlichung und kein Entwurf war.
Ein Feld wird nicht übersetzt. Weder das Feld selbst noch ein übergeordnetes Feld hat localized: true, oder es ist kein text-, textarea- oder richText-Feld.
Die Verbindung zeigt "Couldn't reach this Payload instance" an. Prüfe, ob die Instanz erreichbar ist, der Schlüssel noch gültig ist und eventuelle Gateway-Header noch funktionieren. Aktualisiere die Verbindung unter Settings -> Integrations.
