Plugin Payload CMS
Exposez le schéma de localisation de Payload et informez Lingo.dev des modifications du contenu source, sans modifier le fonctionnement de l’enregistrement dans l’éditeur.
Lingo.dev doit savoir quels champs Payload contiennent du texte localisable et quand leur contenu source change. @lingo.dev/payloadcms fournit les deux mécanismes nécessaires : un point de terminaison de schéma avec authentification et des notifications facultatives de modification du contenu source. La sélection des traductions et leur écriture dans Payload se configurent via l’intégration Payload.
Enregistrer le plugin #
Dans une application Payload 3 existante, installez :
npm install @lingo.dev/payloadcms@0.1.5Ajoutez lingo à la liste des plugins existants de l’application et conservez sa configuration de localisation :
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
localization: {
locales: ["en", "fr"],
defaultLocale: "en",
},
plugins: [lingo()],
});Cet exemple présente les champs pertinents, pas une configuration complète permettant d’utiliser le CMS de façon autonome. Conservez les collections, les globaux, l’adaptateur de base de données, l’éditeur et les autres paramètres requis déjà en place.
Le package exporte lingo et LingoPluginOptions. lingo() renvoie un plugin Payload dont la seule option est webhookUrl?: string. Même enregistré sans cette URL, le plugin expose le point de terminaison de schéma. Vous pouvez donc configurer la découverte du schéma avant les notifications automatiques.
Inspecter le schéma avec l’authentification Payload #
Le plugin ajoute GET /lingo/schema sous le chemin de base de l’API Payload, généralement /api/lingo/schema, tout en conservant les points de terminaison existants. Envoyez une requête pour une collection ou un global connu :
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepageUtilisez les slugs de votre application. Le gestionnaire exige un utilisateur Payload authentifié : une requête non authentifiée renvoie 401, et une entité manquante ou inconnue renvoie 404. L’intégration utilise les droits Payload configurés pour lire ce point de terminaison.
La réponse expose les noms et les types des champs, leurs indicateurs de localisation, leur structure imbriquée et les valeurs par défaut pertinentes après résolution. Elle inclut les groupes, tableaux, blocs et onglets imbriqués pris en charge, ainsi que les schémas de blocs Lexical nécessaires pour repérer le texte. Elle laisse de côté les paramètres d’administration et d’édition sans rapport avec cette tâche, plutôt que de sérialiser toute la configuration Payload.
Les valeurs par défaut sont résolues pour les champs de texte concernés accessibles aux auteurs. Les valeurs par défaut restreintes ou masquées, les champs structurels et les valeurs impossibles à résoudre ou à sérialiser sont exclus des valeurs par défaut renvoyées. Le schéma décrit ce que l’intégration peut examiner ; le récupérer ne déclenche pas de demande de traduction.
Notifier l’intégration après une modification du contenu source #
Après avoir connecté Payload dans Lingo.dev, stockez l’URL d’autorisation fournie dans la configuration du serveur et transmettez-la au plugin :
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 });Utilisez plugin dans le tableau plugins existant à la place de lingo(). Vous choisissez le nom de la variable d’environnement pour votre application. L’URL elle-même autorise les notifications : ne l’incluez ni dans les bundles destinés au navigateur, ni dans le code source committé, ni dans les journaux.
Lorsque l’URL et localization.defaultLocale sont tous deux configurés, le plugin ajoute des hooks afterChange aux collections et aux globaux, tout en conservant les hooks existants. Une notification de collection transmet le slug de la collection, l’ID du document et, éventuellement, le statut du document. Une notification de global transmet son slug. Les données envoyées sont un pointeur, pas le document complet : l’intégration relit le contenu à l’aide des identifiants configurés.
Les modifications explicitement effectuées dans une autre langue sont ignorées. Cela évite que l’écriture des traductions dans la langue cible relance à répétition la traduction du contenu source. Une modification sans langue explicite peut déclencher une notification. La requête a un délai d’expiration de cinq secondes, et les erreurs de transport sont ignorées pour permettre à l’enregistrement dans l’éditeur d’aboutir. Un statut HTTP indiquant un échec ne fait pas non plus échouer l’enregistrement via le hook.
Vérifier le résultat de la connexion #
Vérifiez d’abord que l’intégration peut lire le schéma attendu avec ses identifiants Payload. Effectuez ensuite une modification autorisée du contenu source via le workflow d’intégration et vérifiez le résultat dans la langue cible. Si le contenu source est enregistré mais qu’aucune traduction cible n’arrive, vérifiez l’acceptation de la notification et l’exécution de la traduction : l’enregistrement dans l’éditeur ne prouve pas à lui seul que la notification a été transmise.
Choisissez les collections, les langues cibles et le moteur de localisation dans la configuration de l’intégration Lingo.dev. Ces paramètres ne sont pas des options du plugin : vous pouvez donc les modifier sans remplacer l’enregistrement du plugin dans l’application.