Plugin pro Payload CMS

Zpřístupněte lokalizační schéma systému Payload a informujte Lingo.dev o změnách zdrojového obsahu beze změny chování editoru při ukládání.

Lingo.dev potřebuje vědět, která pole v systému Payload obsahují text k lokalizaci a kdy se jejich zdrojový obsah mění. @lingo.dev/payloadcms zajišťuje obě propojení: endpoint schématu chráněný autentizací a nepovinné notifikace o změnách zdrojového obsahu. Výběr obsahu k překladu a zpětný zápis se nastavují prostřednictvím integrace s Payload.

Zaregistrujte plugin #

Ve stávající aplikaci Payload 3 nainstalujte:

sh
npm install @lingo.dev/payloadcms@0.1.5

Přidejte lingo do stávajícího seznamu pluginů aplikace a zachovejte její konfiguraci lokalizace:

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

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

Ukázka obsahuje pouze relevantní pole, nikoli úplnou samostatnou konfiguraci CMS. Zachovejte stávající kolekce, globální položky, databázový adaptér, editor a další povinná nastavení.

Balíček exportuje lingo a LingoPluginOptions. lingo() vrací plugin pro Payload a jeho jediným parametrem je webhookUrl?: string. Endpoint schématu se zpřístupní i při registraci bez této URL, takže zjišťování schématu můžete nastavit ještě před automatickými notifikacemi.

Prozkoumejte schéma s autentizací systému Payload #

Plugin přidá GET /lingo/schema za základní cestu API systému Payload, obvykle /api/lingo/schema, a zachová přitom stávající endpointy. Odešlete požadavek na známou kolekci nebo globální položku:

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

Použijte slugy ze své aplikace. Obslužná funkce vyžaduje autentizovaného uživatele systému Payload; požadavek bez autentizace vrátí stav 401 a chybějící nebo neznámá entita stav 404. Integrace ke čtení tohoto endpointu používá své nakonfigurované přístupové údaje pro Payload.

Odpověď obsahuje názvy a typy polí, příznaky lokalizace, vnořenou strukturu a relevantní vyhodnocené výchozí hodnoty. Zahrnuje podporované vnořené skupiny, pole, bloky, karty a schémata bloků Lexical potřebná k vyhledání textu. Neserializuje celou konfiguraci systému Payload, ale vynechává nesouvisející nastavení administrace a editoru.

Výchozí hodnoty se vyhodnocují u zahrnutých textových polí určených autorům obsahu. Výstup výchozích hodnot nezahrnuje skryté výchozí hodnoty ani hodnoty s omezeným přístupem, strukturální pole a hodnoty, které nelze vyhodnotit nebo serializovat. Schéma popisuje, co může integrace prozkoumat; jeho načtením se neodesílá požadavek na překlad.

Informujte integraci o změně zdrojového obsahu #

Po připojení systému Payload v Lingo.dev uložte vygenerovanou URL, která sama slouží jako oprávnění, do konfigurace serveru a předejte ji pluginu:

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

Ve stávajícím poli plugins použijte plugin místo lingo(). Název proměnné prostředí si zvolte podle své aplikace. Samotná URL opravňuje k odesílání notifikací; nezahrnujte ji do balíčků pro prohlížeč, zdrojového kódu ukládaného do repozitáře ani logů.

Pokud jsou nastavené URL i localization.defaultLocale, plugin přidá ke kolekcím a globálním položkám hooky afterChange a zachová přitom stávající hooky. Notifikace o změně v kolekci obsahuje její slug, ID dokumentu a nepovinně i stav dokumentu. Notifikace o změně globální položky obsahuje její slug. Odesílaná data představují odkaz, nikoli celý dokument: integrace obsah znovu načte pomocí svých nakonfigurovaných přístupových údajů.

Změny výslovně provedené v jiném jazyce se přeskakují, aby zpětný zápis v cílovém jazyce opakovaně nespouštěl překlad zdrojového obsahu. Změna bez výslovně uvedeného jazyka může vyvolat notifikaci. Požadavek má časový limit pět sekund a chyby přenosu se potlačují, aby se uložení v editoru mohlo dokončit. Ani chybový stav HTTP v tomto hooku nezpůsobí selhání uložení.

Ověřte výsledek připojení #

Nejprve ověřte, že integrace dokáže pomocí svých přístupových údajů pro Payload načíst požadované schéma. Poté prostřednictvím workflow integrace proveďte autorizovanou změnu zdrojového obsahu a zkontrolujte výsledek v cílovém jazyce. Pokud se zdrojový obsah uloží, ale cílový obsah se neobjeví, zkontrolujte přijetí notifikace a průběh překladu. Samotné uložení v editoru není důkazem doručení.

Kolekce, cílové jazyky a lokalizační engine vyberte v konfiguraci integrace v Lingo.dev. Tato nastavení nejsou parametry pluginu, takže je můžete měnit, aniž byste tuto registraci v aplikaci museli nahrazovat.