Payload CMS

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.

Payload CMS ist im Enterprise-Plan enthalten. Wenn auf der Connect-Seite Payload CMS is not on your plan steht, melde dich bei uns — wir kümmern uns darum.

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: true für deine Auth-Collection (normalerweise users), 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.

Verbinde deine Payload-Instanz#

pnpm add @lingo.dev/payloadcms

import { 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,
    }),
  ],
});

Wähle aus, was übersetzt wird#

Die Verbindungsseite hat vier Tabs: Collections, Globals, Workflow runs und Settings.

Der Geltungsbereich wird pro Collection und pro Global festgelegt. Die Tabs Collections und Globals listen alles auf, was deine Instanz anbietet — jeweils eine Zeile pro Eintrag, inklusive der letzten Synchronisierung. Jede Zeile hat einen Sync-Schalter: Wenn du ihn aktivierst, wird ab dann jedes Dokument in dieser Collection oder in diesem Global einbezogen. Die Änderung wird sofort beim Umschalten gespeichert und gilt ohne neues Deployment schon für den nächsten Durchlauf. Mit dem Schalter in der Tabellenkopfzeile schaltest du Sync für alle Einträge in der Liste ein oder aus.

Eine mit no read + update markierte Zeile ist gesperrt: Der Service-Benutzer kann sie nicht lesen und aktualisieren, daher kann sie nicht übersetzt werden. Bei einer mit not localized yet markierten Zeile ist Sync ausgeschaltet.

Sprachen, Engine und Modus änderst du im Tab Settings.

Innerhalb eines Dokuments entscheidet deine Payload-Feldkonfiguration, was übersetzt wird:

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 Durchläufe. Wenn webhookUrl im Plugin gesetzt ist, benachrichtigt jedes Speichern eines Dokuments oder Globals in der Ausgangssprache Lingo.dev. Speicherungen innerhalb eines kurzen Zeitfensters werden zusammengefasst und in einem einzigen Durchlauf verarbeitet. Speicherungen in anderen Sprachen, Entwurfsspeicherungen (es sei denn, die Verbindung ist im Modus Draft) und Inhalte außerhalb deines Geltungsbereichs werden ignoriert.

Manuelle Durchläufe. Zwei Schaltflächen, zwei unterschiedliche Jobs:

Beide befinden sich in der Seitenkopfzeile und gelten dort für alles, bei dem Sync aktiviert ist. Bei „Retranslate“ in der Kopfzeile musst du die Aktion zuerst bestätigen. Wenn du nur einige Collections oder Globals ausführen möchtest, markiere ihre Zeilen: Queue sync (N) und Queue retranslation (N) erscheinen dann und gelten nur für diese Zeilen. Eine Zeile lässt sich erst markieren, wenn ihr Sync-Schalter aktiviert ist.

Beim Verbinden wird noch nichts übersetzt. Um bereits vorhandene Inhalte zu übersetzen, klicke in der Seitenkopfzeile auf Sync. Wenn du später eine Zielsprache hinzufügst, funktioniert es genauso: Der nächste Sync füllt sie aus.

Pro Verbindung kann immer nur ein Durchlauf gleichzeitig laufen. Weitere Anfragen landen in der Warteschlange und starten der Reihe nach.

Einen Lauf verfolgen#

Der Tab Workflow runs listet jeden Durchlauf auf: wann er gestartet wurde, wodurch er ausgelöst wurde (Webhook oder Manual, dann Sync oder Retranslate), welche Sprachen er umfasst hat, wie lange er gedauert hat und welchen Status er hat. Ein Durchlauf in der Warteschlange oder ein laufender Durchlauf hat die Schaltfläche Stop. Öffne eine Zeile, um das Ergebnis pro Sprache zu sehen.

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#

Im Modus Publish lösen nur veröffentlichte Änderungen einen Durchlauf aus, und Übersetzungen werden veröffentlicht, sobald sie geschrieben sind. Payload veröffentlicht immer das gesamte Dokument — daher gehen alle unveröffentlichten Entwurfsänderungen daran zusammen mit der Übersetzung live.

Im Modus Draft lösen auch als Entwurf gespeicherte Änderungen Durchläufe aus. Lingo.dev liest den neuesten Entwurf der Quelle und speichert jede Übersetzung als Entwurf. Für deine Leser ändert sich nichts, bis jemand die Übersetzung in Payload veröffentlicht. Nutze das, wenn du die Übersetzungsqualität auswertest oder wenn Übersetzungen eine Prüfung durchlaufen.

Du kannst den Modus später im Tab Settings ändern.

Verbindung verwalten#

Settings#

Der Tab Settings zeigt die Instanz, aus der die Verbindung liest, welche Collections und Globals Sync aktiviert haben und ob die Verbindung Working oder Cannot be reached ist. Dort kannst du den Namen, die Ausgangssprache, die Zielsprachen, die Engine und den Modus ändern. Bei jeder Änderung bleibt die Webhook-URL gleich — ein neues Deployment ist also nicht nötig.

Die Adresse und der API-Schlüssel werden beim Herstellen der Verbindung festgelegt und können danach nicht mehr geändert werden. Wenn Lingo.dev auf eine andere Adresse oder einen anderen Schlüssel zeigen soll, trenne die Verbindung und stelle sie erneut her.

Verbindung trennen#

Disconnect unten im Tab Settings sorgt dafür, dass Lingo.dev nicht länger aus der Instanz liest und in sie schreibt. Dabei werden die Verbindung, ihr Durchlaufverlauf und der Nachweis 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.

Einschränkungen#

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 lade dann die Verbindungsseite neu. Danach wird der Sync-Schalter der Zeile entsperrt.

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 Durchlauf. Prüfe, ob LINGO_WEBHOOK_URL gesetzt ist, localization konfiguriert ist, die Collection oder das Global im Geltungsbereich liegt, die Speicherung in der Ausgangssprache erfolgt ist und es sich um eine Veröffentlichung statt um einen Entwurf handelt — außer die Verbindung ist im Modus Draft.

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.

Der Tab Settings zeigt die Verbindung als Cannot be reached an. Prüfe, ob die Instanz erreichbar ist, der Schlüssel noch gültig ist und alle Gateway-Header weiterhin funktionieren. Die Adresse und der Schlüssel lassen sich bei einer bestehenden Verbindung nicht bearbeiten. Wenn sich also einer von beiden geändert hat, trenne die Verbindung, stelle sie erneut her und aktualisiere LINGO_WEBHOOK_URL mit der neuen Webhook-URL.

Nächste Schritte#