Plugin für Payload CMS

Stelle das Lokalisierungsschema von Payload bereit und benachrichtige Lingo.dev über Änderungen an Quellinhalten – ohne das Speicherverhalten des Editors zu verändern.

Lingo.dev muss wissen, welche Payload-Felder lokalisierbaren Text enthalten und wann sich deren Quellinhalte ändern. @lingo.dev/payloadcms stellt dafür zwei Verbindungen bereit: einen authentifizierten Schema-Endpunkt und optionale Benachrichtigungen über Änderungen an Quellinhalten. Welche Inhalte übersetzt und wie die Übersetzungen zurückgeschrieben werden, konfigurierst du über die Payload-Integration.

Plugin registrieren #

Installiere in einer bestehenden Payload 3-Anwendung:

sh
npm install @lingo.dev/payloadcms@0.1.5

Füge lingo zur bestehenden Plugin-Liste der Anwendung hinzu und behalte ihre Lokalisierungskonfiguration bei:

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

export default buildConfig({
  localization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  plugins: [lingo()],
});

Das Beispiel zeigt nur die relevanten Felder, keine vollständige, eigenständig nutzbare CMS-Konfiguration. Behalte die bestehenden Sammlungen, globalen Inhalte, den Datenbankadapter, den Editor und alle weiteren erforderlichen Einstellungen bei.

Das Paket exportiert lingo und LingoPluginOptions. lingo() gibt ein Payload-Plugin zurück, dessen einzige Option webhookUrl?: string ist. Auch wenn du das Plugin ohne diese URL registrierst, stellt es den Schema-Endpunkt bereit. So kannst du die Schema-Erkennung konfigurieren, bevor du automatische Benachrichtigungen einrichtest.

Schema über die Payload-Authentifizierung ansehen #

Das Plugin ergänzt GET /lingo/schema relativ zum API-Basispfad von Payload, normalerweise /api/lingo/schema. Bestehende Endpunkte bleiben erhalten. Frage eine bekannte Sammlung oder einen bekannten globalen Inhalt ab:

text
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage

Verwende Slugs aus deiner Anwendung. Der Handler setzt ein authentifiziertes Payload-Benutzerkonto voraus. Eine nicht authentifizierte Anfrage gibt 401 zurück, eine fehlende oder unbekannte Entität 404. Die Integration liest diesen Endpunkt mit ihrer konfigurierten Payload-Zugriffsberechtigung aus.

Die Antwort enthält Feldnamen, Typen, Lokalisierungskennzeichen, verschachtelte Strukturen und relevante aufgelöste Standardwerte. Dazu gehören unterstützte verschachtelte Gruppen, Arrays, Blöcke, Tabs und Lexical-Blockschemata, die zum Auffinden von Text benötigt werden. Nicht relevante Admin- und Editor-Einstellungen werden ausgelassen, statt die gesamte Payload-Konfiguration zu serialisieren.

Standardwerte werden für die berücksichtigten Textfelder aufgelöst, die Autorinnen und Autoren zur Verfügung stehen. Eingeschränkte oder ausgeblendete Standardwerte, strukturelle Felder und Werte, die sich nicht auflösen oder serialisieren lassen, sind von der Ausgabe der Standardwerte ausgeschlossen. Das Schema beschreibt, was die Integration untersuchen kann. Sein Abruf fordert keine Übersetzung an.

Integration nach einer Änderung am Quellinhalt benachrichtigen #

Nachdem du Payload in Lingo.dev verbunden hast, speichere die bereitgestellte Berechtigungs-URL in der Serverkonfiguration und übergib sie an das Plugin:

ts
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 });

Verwende plugin im bestehenden plugins-Array anstelle von lingo(). Den Namen der Umgebungsvariablen legst du für deine Anwendung selbst fest. Die URL selbst autorisiert die Benachrichtigungen. Sie darf daher nicht in Browser-Bundles, in per Commit gespeichertem Quellcode oder in Protokollen enthalten sein.

Wenn sowohl die URL als auch localization.defaultLocale konfiguriert sind, ergänzt das Plugin Sammlungen und globale Inhalte um afterChange-Hooks. Bestehende Hooks bleiben erhalten. Eine Benachrichtigung für eine Sammlung sendet deren Slug, die Dokument-ID und optional den Dokumentstatus. Eine Benachrichtigung für einen globalen Inhalt sendet dessen Slug. Die Nutzdaten enthalten einen Verweis, nicht das vollständige Dokument: Die Integration liest den Inhalt mit ihren konfigurierten Zugangsdaten erneut aus.

Änderungen, die explizit in einer anderen Sprache vorgenommen werden, werden übersprungen. So löst das Zurückschreiben in der Zielsprache nicht immer wieder eine Übersetzung des Quellinhalts aus. Eine Änderung ohne explizite Sprachangabe kann eine Benachrichtigung auslösen. Für die Anfrage gilt ein Zeitlimit von fünf Sekunden. Übertragungsfehler werden abgefangen und ignoriert, damit der Speichervorgang im Editor abgeschlossen werden kann. Auch ein nicht erfolgreicher HTTP-Status führt durch den Hook nicht dazu, dass der Speichervorgang fehlschlägt.

Ergebnis der Verbindung bestätigen #

Stelle zunächst sicher, dass die Integration das vorgesehene Schema mit ihren Payload-Zugangsdaten auslesen kann. Nimm dann über den Integrations-Workflow eine autorisierte Änderung am Quellinhalt vor und sieh dir das Ergebnis in der Zielsprache an. Wenn der Quellinhalt gespeichert wird, aber kein Zielinhalt ankommt, sieh nach, ob die Benachrichtigung angenommen wurde und wie der Übersetzungslauf verlaufen ist. Ein erfolgreicher Speichervorgang im Editor allein belegt nicht, dass die Benachrichtigung zugestellt wurde.

Wähle Sammlungen, Zielsprachen und die Lokalisierungs-Engine in der Integrationskonfiguration von Lingo.dev aus. Diese Einstellungen sind keine Plugin-Optionen. Du kannst sie daher ändern, ohne die Plugin-Registrierung in der Anwendung zu ersetzen.