Payload CMS

Traduisez les champs localisés de Payload 3, préservez la structure des ressources et choisissez comment répercuter les modifications de la source dans les langues cibles.

Payload prévoit déjà un emplacement pour les versions linguistiques de chaque champ localisé. La connexion Lingo.dev lit les champs source sélectionnés, les traduit à l'aide d'un moteur de localisation et écrit les résultats dans ces mêmes ressources, pour les langues cibles. Les collections, les globaux et la publication restent dans Payload.

Dans le menu de navigation de Studio 2.5, ouvrez Studio 2.5 → Intégrations plutôt que Paramètres → Intégrations. Les liens existants de connexion et de configuration restent valides.

Commencez par une seule ressource et une synchronisation manuelle. Après avoir vérifié le résultat, ajoutez des notifications de modification de la source si vous souhaitez que la traduction suive automatiquement les changements.

L'intégration Payload CMS nécessite le forfait Enterprise. Consultez les tarifs pour connaître la disponibilité actuelle. Dans Paramètres → Intégrations, la mention Non disponible avec votre forfait apparaît à côté de Payload lorsque l'organisation doit disposer du forfait requis.

Préparer Payload et un utilisateur de service #

Utilisez Payload 3 avec la localisation configurée. La traduction de texte enrichi prend en charge l'éditeur Lexical, mais pas l'ancien éditeur Slate. Votre instance doit être accessible à Lingo.dev via HTTPS.

Créez un utilisateur de service dans une collection d'authentification avec useAPIKey: true, généralement users. Accordez-lui des droits de lecture et de mise à jour sur chaque collection ou global que vous souhaitez traduire. Les écritures sont attribuées à cet utilisateur. Si une passerelle exige des en-têtes supplémentaires, renseignez-les lors de la connexion et gardez leurs valeurs secrètes.

Faites correspondre la langue source de la connexion au paramètre localization.defaultLocale de Payload, dont le plugin surveille les modifications. Les codes des langues source et cibles doivent correspondre exactement aux codes configurés dans Payload : en et en-US désignent des langues différentes. Choisissez un moteur de localisation accessible dans l'organisation Lingo.dev connectée. Si vous ne pouvez pas ajouter la connexion, vérifiez les autorisations de votre organisation et son droit d'accès aux connexions.

Connecter l'instance et exposer son schéma #

Ouvrez Paramètres → Intégrations et sélectionnez Connecter pour Payload CMS. Saisissez un nom de connexion, l'adresse racine de l'instance, la collection d'authentification, la clé API de service et les éventuels en-têtes de passerelle. Sélectionnez Connecter pour vérifier l'accès et enregistrer la connexion. Conservez l'URL du webhook qui s'affiche ensuite : elle servira aux notifications automatiques.

Installez le plugin dans le projet Payload :

bash
pnpm add @lingo.dev/payloadcms

Ajoutez lingo au tableau plugins existant. Cet extrait présente la configuration du plugin ; conservez les collections, les globaux, la localisation et les autres plugins de votre projet :

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

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

Le plugin enregistre toujours GET /api/lingo/schema. Lingo.dev utilise ce point de terminaison pour identifier les champs localisés. Vous pouvez créer une connexion avant d'installer le plugin, mais la traduction nécessite le point de terminaison du schéma.

Pour activer les notifications automatiques, copiez l'URL du webhook de la connexion dans la variable d'environnement LINGO_WEBHOOK_URL de Payload. Traitez cette URL comme un accès secret : toute personne qui la possède peut envoyer des requêtes de notification. Redéployez Payload après toute modification du plugin ou de l'environnement. Pour une traduction uniquement manuelle, omettez webhookUrl ; le plugin exposera tout de même le schéma.

Dans Studio, sélectionnez l'instance sous Connecté, puis Configurer. Choisissez son moteur de localisation, ses langues source et cibles et son mode d'écriture des résultats. Sélectionnez Continuer, puis choisissez les collections et les globaux à traduire. Les modes de publication sont décrits ci-dessous.

Traduire une ressource #

Choisissez une collection ou un global contenant un court champ de texte localisé, ainsi qu'une langue cible. Notez les valeurs source et cible actuelles de ce champ dans Payload avant de lancer la synchronisation.

Choisissez le mode en fonction du résultat de publication souhaité :

ModeSource et écriture des résultats
BrouillonLit le contenu source en brouillon et écrit les champs traduits sous forme de brouillons pour relecture dans Payload.
PublierTraite les modifications publiées et écrit les traductions sous forme de contenu publié.

Payload conserve un seul brouillon partagé par document et le publie en entier. Ajouter une traduction à un document publié qui contient des modifications non publiées entraînerait donc aussi la publication de ces modifications. Le mode Publier laisse alors le document inchangé et signale que sa traduction a échoué. Publiez les modifications ou rétablissez la version publiée dans Payload, puis relancez la synchronisation. Pour voir ces modifications, l’utilisateur associé à la clé API doit disposer d’un accès readVersions à toutes les versions des collections et des globaux sélectionnés ; si cet accès est filtré, le mode Publier laisse leurs documents publiés inchangés. Un document qui n’a jamais été publié n’est pas soumis à cette vérification : le mode Publier y écrit la traduction, mais le document reste à l’état de brouillon. La vérification a lieu juste avant chaque écriture : un brouillon enregistré entre-temps peut donc malgré tout être publié avec la traduction. Évitez d’enregistrer des brouillons pendant qu’une synchronisation écrit dans les documents concernés, puis vérifiez leur état de publication. Le comportement des brouillons dépend également de votre configuration Payload ; vérifiez la version déjà en ligne lorsque vous testez une mise à jour.

Lancez Synchroniser, ouvrez l'exécution de workflow correspondante et vérifiez directement le champ cible dans Payload. Contrôlez la formulation, les liens, la structure du texte enrichi, la langue et l'état de publication. Consultez ensuite le contenu sur le site qui l'utilise. La connexion seule ne traduit pas le catalogue.

La première synchronisation conserve les traductions existantes complètes sans les remplacer. Elle remplit les champs manquants, y compris ceux dont la valeur actuelle ne fait que reprendre la valeur par défaut de Payload. Si un champ a été conservé, comparez sa valeur à cet état avant de demander son remplacement.

Sélectionner les ressources et les champs #

Les tableaux Collections et Globaux disposent d'interrupteurs Synchroniser dont l'état est conservé. Sélectionner une collection inclut ses documents ; sélectionner un global inclut cette ressource. Les actions de l'en-tête traitent les ressources activées. Lorsque des actions sur les lignes sélectionnées sont proposées, elles mettent en file d'attente le périmètre choisi sans modifier la sélection permanente de la connexion.

Dans ces ressources, le schéma sélectionne les champs localisés text, textarea et les champs richText de Lexical. Il parcourt également le texte des groupes, tableaux, blocs et onglets localisés, y compris les blocs de texte enrichi imbriqués et intégrés dans le texte.

Les champs non localisés et les valeurs structurelles telles que id, blockType et blockName restent en dehors du texte à traduire. Les listes de sélection, les nombres, les relations, les fichiers téléversés, le code et le JSON arbitraire ne deviennent pas traduisibles simplement parce que leur collection est sélectionnée. Pour inclure un autre champ de texte, configurez sa localisation dans Payload et redéployez.

Le traitement Lexical préserve le contexte des phrases malgré la mise en forme intégrée et les liens, puis reconstruit l'arborescence avec ses liens, ses médias et ses blocs. Testez un document représentatif avant d'élargir le périmètre, surtout si votre projet utilise des champs personnalisés ou des extensions d'éditeur.

Maintenir les traductions à jour au fil des modifications de la source #

Lorsqu'une URL de webhook et une langue par défaut sont configurées, le plugin envoie des notifications après les modifications dans la langue source. Une notification contient une référence à une ressource, et non le corps du document. Lingo.dev relit le contenu à l'aide des identifiants de service enregistrés, applique le périmètre et le mode de la connexion, puis regroupe les notifications rapprochées dans le temps avant de les traiter.

Les écritures dans une langue cible ne déclenchent pas de nouvelle traduction. Les échecs de notification ne font pas non plus échouer l'enregistrement dans l'éditeur : un enregistrement réussi ne suffit donc pas à confirmer la transmission de la notification. Si une modification n'a pas été prise en compte, consultez l'historique des exécutions et utilisez une synchronisation manuelle pour remettre le contenu à jour. Les enregistrements de brouillons sont pris en compte en mode Brouillon ; un enregistrement dans une langue cible ou une ressource hors périmètre ne constitue pas une modification de la source pour cette connexion.

Utilisez Synchroniser pour traiter les modifications de la source et compléter le contenu cible manquant. Cette action compare le contenu à l'état de référence disponible. Lorsqu'un artefact source antérieur n'est pas disponible, la récupération peut régénérer le contenu concerné : vérifiez donc les différences plutôt que de supposer que toutes les modifications manuelles seront conservées. Après avoir ajouté une langue cible, lancez la synchronisation pour y ajouter le contenu.

Utilisez Retraduire lorsque vous souhaitez remplacer les traductions sélectionnées, y compris les champs modifiés à la main. Par exemple, une modification importante des instructions du moteur de localisation peut justifier un nouveau résultat, même si la source est inchangée. Les requêtes sont mises en file d'attente après l'exécution active de la connexion ; répéter la même action n'accélère pas son traitement.

Récupérer un document modifié ou partiellement écrit #

L'étape d'écriture des résultats relit le contenu source. Si une personne l'a modifié dans l'éditeur après la planification, le document est ignoré pour éviter d'appliquer les valeurs traduites à une autre révision ou à un tableau dont l'ordre a changé. Une synchronisation ultérieure remet le contenu à jour à partir de la nouvelle source.

Les exécutions en échec ou annulées conservent les écritures réussies. Dans Exécutions de workflow, distinguez les tâches terminées, à jour, ignorées, en échec et annulées, puis vérifiez les ressources concernées avant de réessayer. Arrêter annule les tâches actives lorsque cette option est disponible, sans annuler les écritures déjà effectuées dans les champs. Un résultat « à jour » signifie qu'aucune modification sélectionnée n'était à traiter.

Si aucun résultat n'apparaît, vérifiez le point de terminaison du schéma, la localisation et le type des champs, les droits de lecture et de mise à jour de l'utilisateur de service, le code exact de la langue, la sélection des ressources à synchroniser, le mode et l'environnement du webhook. Résolvez tout problème d'instance inaccessible ou de clé refusée avant de demander une retraduction.

Modifier les paramètres ou déconnecter #

Modifiez la sélection des ressources, les langues, le moteur de localisation et le mode dans Studio. Renommez la connexion ou gérez ses identifiants dans Paramètres → Intégrations. Ces modifications ne changent pas son URL de webhook.

Pour renouveler la clé API, ouvrez la connexion dans Paramètres → Intégrations et sélectionnez Remplacer la clé. Saisissez une clé provenant de la même collection d'authentification et renseignez à nouveau tous les en-têtes personnalisés dont l'instance a encore besoin ; les en-têtes fournis remplacent ceux qui sont enregistrés.

Changer l'adresse de l'instance nécessite une nouvelle connexion. Configurez son périmètre de traduction et mettez à jour l'environnement de Payload avec la nouvelle URL de webhook avant de vous appuyer à nouveau sur les notifications automatiques.

La déconnexion supprime l'historique local et l'état de synchronisation de la connexion, et met fin aux futures lectures et écritures. Le contenu déjà traduit reste dans Payload. Supprimez l'ancienne valeur de la variable d'environnement du webhook ou le hook, et révoquez séparément la clé de service si elle n'est plus nécessaire.

Une nouvelle connexion établit un nouvel état de référence. Sa première synchronisation conserve les traductions existantes admissibles et complète le contenu manquant ; elle ne restaure pas l'historique local des exécutions d'une connexion précédente. Vérifiez cette première exécution comme vous le feriez pour toute nouvelle connexion.