Payload CMS

Übersetze lokalisierte Felder in Payload 3, behalte die Ressourcenstruktur bei und lege fest, wie Änderungen am Quellinhalt in die Zielsprachen übernommen werden.

Payload sieht für jedes lokalisierte Feld bereits eigene Sprachversionen vor. Die Lingo.dev-Verbindung liest ausgewählte Quellfelder, übersetzt sie mit einer Lokalisierungs-Engine und schreibt die Ergebnisse in die Zielsprachen derselben Ressourcen zurück. Sammlungen, globale Ressourcen und die Veröffentlichung bleiben in Payload.

Öffne in der Navigation von Studio 2.5 Studio 2.5 → Integrationen statt Einstellungen → Integrationen. Vorhandene Links zum Verbinden und Einrichten funktionieren weiterhin.

Starte mit einer Ressource und einer manuellen Synchronisierung. Sieh dir das Ergebnis an und richte anschließend Benachrichtigungen über Änderungen am Quellinhalt ein, wenn Bearbeitungen automatisch eine Übersetzung auslösen sollen.

Die Payload-CMS-Integration erfordert den Enterprise-Tarif. Informationen zur aktuellen Verfügbarkeit findest du unter Preise. Unter Einstellungen → Integrationen steht neben Payload Nicht in deinem Tarif verfügbar, wenn deine Organisation den entsprechenden Tarifzugang benötigt.

Payload und einen Dienstnutzer vorbereiten #

Verwende Payload 3 mit eingerichteter Lokalisierung. Die Rich-Text-Übersetzung unterstützt den Lexical-Editor, nicht jedoch den älteren Slate-Editor. Deine Instanz muss für Lingo.dev über HTTPS erreichbar sein.

Erstelle einen Dienstnutzer in einer Authentifizierungssammlung mit useAPIKey: true, üblicherweise users. Gib diesem Nutzer Lese- und Aktualisierungszugriff auf alle Sammlungen und globalen Ressourcen, die du übersetzen möchtest. Schreibvorgänge werden diesem Nutzer zugeordnet. Falls ein Gateway zusätzliche Header erfordert, gib sie beim Verbinden an und halte ihre Werte geheim.

Wähle als Quellsprache der Verbindung die in Payload unter localization.defaultLocale festgelegte Sprache, deren Änderungen das Plugin erfasst. Die Codes für Quell- und Zielsprachen müssen exakt mit den in Payload konfigurierten Codes übereinstimmen: en und en-US bezeichnen unterschiedliche Sprachen. Wähle eine Lokalisierungs-Engine, auf die du in der verbundenen Lingo.dev-Organisation zugreifen kannst. Falls du keine Verbindung hinzufügen kannst, kontrolliere die Berechtigungen deiner Organisation und ihre Freischaltung für Verbindungen.

Die Instanz verbinden und ihr Schema bereitstellen #

Öffne Einstellungen → Integrationen und wähle bei Payload CMS Verbinden. Gib einen Namen für die Verbindung, die Basisadresse der Instanz, die Authentifizierungssammlung, den API-Schlüssel des Dienstnutzers und gegebenenfalls Gateway-Header ein. Wähle Verbinden, um den Zugriff zu verifizieren und die Verbindung zu speichern. Bewahre die anschließend angezeigte Webhook-URL für automatische Benachrichtigungen auf.

Installiere das Plugin im Payload-Projekt:

bash
pnpm add @lingo.dev/payloadcms

Füge lingo zum vorhandenen plugins-Array hinzu. Dieser Ausschnitt zeigt die Plugin-Konfiguration; behalte die Sammlungen, globalen Ressourcen, Lokalisierung und übrigen Plugins deines Projekts bei:

ts
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";

export default buildConfig({
  plugins: [
    lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
  ],
});

Das Plugin registriert immer GET /api/lingo/schema. Lingo.dev nutzt diesen Endpunkt, um lokalisierte Felder zu erkennen. Du kannst eine Verbindung schon vor der Installation des Plugins erstellen. Für die Übersetzung ist jedoch der Schema-Endpunkt erforderlich.

Kopiere für automatische Benachrichtigungen die Webhook-URL der Verbindung in die Payload-Umgebungsvariable LINGO_WEBHOOK_URL. Behandle sie wie einen geheimen Zugangsschlüssel: Wer die URL besitzt, kann Benachrichtigungsanfragen senden. Stelle Payload nach Änderungen am Plugin oder an den Umgebungsvariablen erneut bereit. Wenn du ausschließlich manuell übersetzen möchtest, lasse webhookUrl weg; das Plugin stellt das Schema trotzdem bereit.

Wähle in Studio unter Verbunden die Instanz und anschließend Einrichten. Lege die Lokalisierungs-Engine, die Quell- und Zielsprachen sowie den Rückschreibmodus fest. Wähle Weiter und dann die Sammlungen und globalen Ressourcen, die du übersetzen möchtest. Die Veröffentlichungsmodi werden weiter unten beschrieben.

Eine Ressource übersetzen #

Wähle eine Sammlung oder globale Ressource mit einem kurzen lokalisierten Textfeld sowie eine Zielsprache. Notiere vor der Synchronisierung die aktuellen Quell- und Zielwerte in Payload.

Wähle den Modus passend zum gewünschten Veröffentlichungsergebnis:

ModusQuellinhalt und Rückschreiben
EntwurfLiest Quellinhalte aus Entwürfen und schreibt übersetzte Felder als Entwürfe zur Prüfung in Payload zurück.
VeröffentlichenVerarbeitet veröffentlichte Änderungen und schreibt Übersetzungen als veröffentlichte Inhalte zurück.

Payload verwaltet pro Dokument einen gemeinsamen Entwurf und veröffentlicht ihn vollständig. Wird eine Übersetzung in ein bereits veröffentlichtes Dokument mit unveröffentlichten Änderungen geschrieben, werden deshalb auch diese Änderungen veröffentlicht. Der Veröffentlichungsmodus lässt ein solches Dokument daher unverändert und meldet die Übersetzung als fehlgeschlagen. Veröffentliche die Änderungen in Payload oder setze das Dokument auf die veröffentlichte Version zurück. Führe anschließend Sync erneut aus. Damit diese Änderungen sichtbar sind, benötigt das mit dem API-Schlüssel verknüpfte Benutzerkonto readVersions-Zugriff auf alle Versionen der ausgewählten Sammlungen und Globalen. Ist dieser Zugriff durch Filter eingeschränkt, lässt der Veröffentlichungsmodus deren veröffentlichte Dokumente unverändert. Bei einem Dokument, das noch nie veröffentlicht wurde, entfällt diese Kontrolle: Der Veröffentlichungsmodus schreibt die Übersetzung in das Dokument, das weiterhin ein Entwurf bleibt. Die Kontrolle erfolgt unmittelbar vor jedem Schreibvorgang. Ein zwischenzeitlich gespeicherter Entwurf kann daher trotzdem zusammen mit der Übersetzung veröffentlicht werden. Speichere keine Entwürfe, während eine Synchronisierung in die betreffenden Dokumente schreibt, und sieh anschließend deren Veröffentlichungsstatus ein. Wie sich Entwürfe verhalten, hängt auch von deiner Payload-Konfiguration ab. Kontrolliere beim Testen einer Aktualisierung die bestehende Live-Version.

Führe Synchronisieren aus, öffne die zugehörige Workflow-Ausführung und sieh dir das tatsächliche Zielfeld in Payload an. Kontrolliere Formulierungen, Links, Rich-Text-Struktur, Sprache und Veröffentlichungsstatus. Lies den Inhalt anschließend auf der Website, die ihn verwendet. Allein durch das Verbinden wird der Katalog nicht übersetzt.

Die erste Synchronisierung behält vollständige vorhandene Übersetzungen bei, ohne sie zu ersetzen. Sie füllt fehlende Felder, auch solche, deren aktueller Wert lediglich den Payload-Standardwert wiederholt. Wurde ein Feld beibehalten, vergleiche seinen Wert mit dem Stand vor der Synchronisierung, bevor du eine Ersetzung anforderst.

Ressourcen und Felder auswählen #

Die Tabellen Sammlungen und Globale bieten Synchronisieren-Schalter, deren Einstellung dauerhaft gespeichert wird. Die Auswahl einer Sammlung umfasst ihre Dokumente; die Auswahl einer globalen Ressource umfasst diese Ressource. Aktionen im Tabellenkopf verarbeiten aktivierte Ressourcen. Sind Aktionen für ausgewählte Zeilen verfügbar, reihen sie nur die ausgewählten Ressourcen zur Verarbeitung ein, ohne die dauerhaft gespeicherte Auswahl der Verbindung zu ändern.

Innerhalb dieser Ressourcen wählt das Schema lokalisierte text-, textarea- und Lexical-richText-Felder aus. Es erfasst auch Text in lokalisierten Gruppen, Arrays, Blöcken und Tabs, einschließlich verschachtelter und eingebetteter Rich-Text-Blöcke.

Nicht lokalisierte Felder und strukturelle Werte wie id, blockType und blockName gehören nicht zum Übersetzungstext. Auswahlfelder, Zahlen, Beziehungen, Uploads, Code und beliebiges JSON werden nicht allein dadurch übersetzbar, dass ihre Sammlung ausgewählt ist. Um ein weiteres Textfeld einzubeziehen, richte dessen Lokalisierung in Payload ein und stelle das Projekt erneut bereit.

Die Lexical-Verarbeitung erhält den Satzkontext über Inline-Formatierungen und Links hinweg und baut anschließend die Baumstruktur mit ihren Links, Medien und Blöcken wieder auf. Teste ein repräsentatives Dokument, bevor du den Umfang erweiterst, insbesondere wenn dein Projekt benutzerdefinierte Felder oder Editor-Erweiterungen verwendet.

Übersetzungen bei Änderungen am Quellinhalt aktuell halten #

Wenn eine Webhook-URL und eine Standardsprache eingerichtet sind, sendet das Plugin nach Änderungen in der Quellsprache Benachrichtigungen. Eine Benachrichtigung enthält einen Verweis auf eine Ressource, nicht den Dokumentinhalt. Lingo.dev liest den Inhalt mit den gespeicherten Zugangsdaten des Dienstnutzers erneut, berücksichtigt den Umfang und Modus der Verbindung und fasst zeitlich nahe beieinanderliegende Benachrichtigungen vor der Verarbeitung zusammen.

Schreibvorgänge in Zielsprachen lösen keine weitere Übersetzung aus. Auch Fehler beim Senden von Benachrichtigungen verhindern nicht, dass Inhalte im Editor gespeichert werden. Erfolgreiches Speichern allein bestätigt daher nicht die Zustellung. Falls eine Änderung nicht erfasst wurde, sieh dir den Ausführungsverlauf an und gleiche den Inhalt mit einer manuellen Synchronisierung ab. Das Speichern von Entwürfen ist im Modus „Entwurf“ relevant; das Speichern in einer Zielsprache oder einer Ressource außerhalb des festgelegten Umfangs zählt für diese Verbindung nicht als Änderung am Quellinhalt.

Verwende Synchronisieren für geänderte Quellinhalte und fehlende Zielinhalte. Dabei werden die Inhalte mit dem verfügbaren Referenzstand verglichen. Wenn ein früheres Quellartefakt nicht verfügbar ist, können die betroffenen Inhalte bei der Wiederherstellung neu erzeugt werden. Sieh dir daher die Unterschiede an, statt davon auszugehen, dass jede manuelle Bearbeitung erhalten bleibt. Führe nach dem Hinzufügen einer Zielsprache eine Synchronisierung aus, um ihre Inhalte zu ergänzen.

Verwende Neu übersetzen, wenn du die ausgewählten Übersetzungen einschließlich manuell bearbeiteter Felder ersetzen möchtest. Eine wesentliche Änderung der Anweisungen für die Lokalisierungs-Engine kann beispielsweise neue Ergebnisse rechtfertigen, auch wenn der Quellinhalt unverändert ist. Anfragen werden hinter der aktiven Ausführung der Verbindung eingereiht; das wiederholte Auslösen derselben Aktion beschleunigt den Abschluss nicht.

Ein geändertes oder teilweise geschriebenes Dokument wiederherstellen #

Beim Rückschreiben wird der Quellinhalt erneut gelesen. Wurde er nach der Planung im Editor geändert, wird das Dokument übersprungen, statt übersetzte Werte auf eine andere Revision oder eine geänderte Array-Reihenfolge anzuwenden. Eine spätere Synchronisierung gleicht den neuen Quellinhalt ab.

Bei fehlgeschlagenen oder abgebrochenen Ausführungen bleiben erfolgreiche Schreibvorgänge erhalten. Unterscheide unter Workflow-Ausführungen zwischen abgeschlossenen, aktuellen, übersprungenen, fehlgeschlagenen und abgebrochenen Vorgängen und sieh dir die betroffenen Ressourcen vor einem erneuten Versuch an. Stopp bricht aktive Vorgänge ab, sofern verfügbar; bereits geschriebene Felder werden dadurch nicht zurückgesetzt. Das Ergebnis „Aktuell“ bedeutet, dass keine ausgewählte Änderung zu verarbeiten war.

Wenn keine Ergebnisse erscheinen, kontrolliere den Schema-Endpunkt, die Lokalisierung und den Typ der Felder, die Lese- und Aktualisierungsberechtigungen des Dienstnutzers, den exakten Sprachcode, die zur Synchronisierung ausgewählten Ressourcen, den Modus und die Webhook-Umgebungsvariablen. Sorge dafür, dass die Instanz erreichbar ist und der Schlüssel akzeptiert wird, bevor du eine erneute Übersetzung anforderst.

Einstellungen ändern oder die Verbindung trennen #

Ändere die Ressourcenauswahl, die Sprachen, die Lokalisierungs-Engine und den Modus in Studio. Unter Einstellungen → Integrationen kannst du die Verbindung umbenennen oder ihre Zugangsdaten verwalten. Die Webhook-URL bleibt bei diesen Änderungen erhalten.

Um den API-Schlüssel auszutauschen, öffne die Verbindung unter Einstellungen → Integrationen und wähle Schlüssel ersetzen. Gib einen Schlüssel aus derselben Authentifizierungssammlung ein und trage alle benutzerdefinierten Header erneut ein, die die Instanz weiterhin benötigt. Die angegebenen Header ersetzen die gespeicherten.

Eine Änderung der Instanzadresse erfordert eine neue Verbindung. Lege deren Übersetzungsumfang fest und hinterlege die neue Webhook-URL in der Payload-Umgebung, bevor du dich wieder auf automatische Benachrichtigungen verlässt.

Beim Trennen werden der lokale Verlauf und der Synchronisierungsstatus der Verbindung entfernt. Künftige Lese- und Schreibvorgänge werden beendet. Vorhandene übersetzte Inhalte bleiben in Payload. Entferne den alten Webhook-Wert aus der Umgebung oder den alten Hook und widerrufe den Dienstschlüssel separat, wenn er nicht mehr benötigt wird.

Eine neue Verbindung legt einen neuen Referenzstand fest. Ihre erste Synchronisierung behält vorhandene Übersetzungen bei, die die Voraussetzungen erfüllen, und füllt Lücken. Sie stellt den lokalen Ausführungsverlauf einer früheren Verbindung nicht wieder her. Sieh dir diese erste Ausführung genauso an wie bei jeder neuen Verbindung.