Payload CMS

Connectez votre Payload CMS à un moteur de localisation, choisissez les collections et globals à couvrir, puis laissez Lingo.dev traduire leurs champs localisés dans vos langues cibles et les réécrire dans Payload pour chaque langue.

Compatible avec les projets Payload 3 où la localisation est activée et qui utilisent l’éditeur de texte enrichi Lexical. L’ancien éditeur Slate n’est pas pris en charge. Les champs localisés text, textarea et richText sont traduits. Tout le reste du document reste tel quel.

Payload CMS est disponible avec le plan Enterprise. Si la page Connecter affiche Payload CMS is not on your plan, contactez-nous et nous nous en occuperons.

Avant de commencer#

Vous avez besoin de trois éléments :

• Payload 3 avec la localisation configurée. Assurez-vous que vos langues source et cible correspondent aux langues définies dans votre configuration Payload.
• Un utilisateur de service avec une clé API. Activez useAPIKey: true sur votre collection d'authentification (généralement users), créez un utilisateur pour Lingo.dev, puis générez-lui une clé API dans l'interface d'administration de Payload. Cet utilisateur doit disposer d'un accès en lecture et en mise à jour à chaque collection et global que vous souhaitez traduire.
• Un moteur de localisation. Son glossaire, sa voix de marque et ses règles façonnent les traductions.

Connectez votre instance Payload#

pnpm add @lingo.dev/payloadcms

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

export default buildConfig({
  // ...your collections, globals, and localization config
  plugins: [
    lingo({
      webhookUrl: process.env.LINGO_WEBHOOK_URL,
    }),
  ],
});

Choisissez ce qui est traduit#

La page de connexion comporte quatre onglets : Collections, Globals, Exécutions de workflow et Paramètres.

La portée se définit par collection et par global. Les onglets Collections et Globals listent tout ce que votre instance propose, à raison d’une ligne par élément, avec la date de la dernière synchronisation. Chaque ligne comporte un interrupteur Sync : activez-le et tous les documents de cette collection, ou de ce global, seront couverts à partir de ce moment. La modification est enregistrée dès que vous basculez l’interrupteur et s’applique à la prochaine exécution sans redéploiement. L’interrupteur dans l’en-tête du tableau active ou désactive Sync pour tous les éléments de la liste.

Une ligne marquée no read + update est verrouillée : l’utilisateur de service ne peut ni la lire ni la mettre à jour, donc elle ne peut pas être traduite. Une ligne marquée not localized yet a Sync désactivé.

Les langues, le moteur et le mode se modifient dans l’onglet Paramètres.

Dans un document, c’est la configuration des champs Payload qui détermine ce qui est traduit :

Le texte enrichi est traduit sous forme d’arbre Lexical. La mise en forme, les liens, les téléversements et la structure des blocs sont préservés, et seul le texte qu’ils contiennent est remplacé. Une phrase interrompue par du texte en gras ou par un lien est traduite comme une seule phrase.

Pour inclure un champ dans la portée, marquez-le localized: true dans Payload puis redéployez. Il sera pris en compte à la prochaine exécution.

Synchroniser et retraduire#

Exécutions automatiques. Avec webhookUrl défini dans le plugin, chaque enregistrement d’un document ou d’un global dans la langue source notifie Lingo.dev. Les enregistrements effectués dans un court intervalle sont regroupés en une seule exécution. Les enregistrements dans d’autres langues, les brouillons enregistrés (sauf si la connexion est en mode Brouillon) et le contenu hors de votre portée sont ignorés.

Exécutions manuelles. Deux boutons, deux actions différentes :

Les deux se trouvent dans l’en-tête de la page, où ils couvrent tout ce pour quoi Sync est activé. Retranslate depuis l’en-tête vous demande d’abord de confirmer. Pour lancer l’exécution sur certaines collections ou certains globals seulement, cochez leurs lignes : Queue sync (N) et Queue retranslation (N) apparaissent et ne couvrent que ces lignes. Une ligne ne peut être cochée que si son interrupteur Sync est activé.

Rien n’est traduit au moment de la connexion. Pour traduire ce que vous avez déjà, cliquez sur Sync dans l’en-tête de la page. Ajouter une langue cible plus tard fonctionne de la même façon : la synchronisation suivante la remplira.

Une seule exécution par connexion peut être en cours à la fois. Les demandes supplémentaires sont mises en file d’attente et démarrent dans l’ordre.

Suivre une exécution#

L’onglet Exécutions de workflow liste chaque exécution : son heure de début, ce qui l’a déclenchée (Webhook ou Manual, puis Sync ou Retranslate), les langues couvertes, sa durée et son statut. Une exécution en attente ou en cours comporte un bouton Stop. Ouvrez une ligne pour voir le résultat par langue.

En cas d’échec, l’exécution conserve ce qu’elle a déjà écrit. Le message d’erreur répertorie les documents qui n’ont pas été écrits, et la prochaine Sync réessaie de les traiter. Si un éditeur enregistre un document pendant l’exécution, il est ignoré et repris lors de l’exécution suivante.

Où arrivent les traductions#

Chaque traduction est écrite dans le même document ou global, sous sa langue cible, selon le modèle de localisation natif de Payload. Seuls les champs traduits sont écrits. Tous les autres champs restent inchangés. Les réécritures s’exécutent avec l’utilisateur de service et ne déclenchent pas de nouvelle exécution.

Les traductions existantes sont conservées. Lors de la première synchronisation d'un document, tout ce qu'une langue cible contient déjà reste en place, et seuls les champs manquants sont traduits. Un champ qui contient encore sa valeur par défaut Payload est considéré comme manquant. Utilisez Retranslate pour remplacer les traductions existantes.

Brouillons et publications#

En mode Publier, seules les modifications publiées démarrent une exécution, et les traductions sont publiées dès qu’elles sont écrites. Payload publie le document entier, donc toute modification de brouillon non publiée qu’il contient est mise en ligne avec la traduction.

En mode Brouillon, les enregistrements de brouillon démarrent aussi des exécutions. Lingo.dev lit le dernier brouillon de la source et enregistre chaque traduction comme brouillon. Rien ne change pour vos lecteurs tant que quelqu’un ne publie pas la traduction dans Payload. Utilisez ce mode pendant l’évaluation de la qualité de traduction ou lorsque les traductions passent par une relecture.

Vous pouvez modifier le mode plus tard dans l’onglet Paramètres.

Gérer la connexion#

Paramètres#

L’onglet Paramètres affiche l’instance que la connexion lit, quelles collections et quels globals ont Sync activé, et si la connexion est Working ou Cannot be reached. Il vous permet de modifier le nom, la langue source, les langues cibles, le moteur et le mode. Chaque modification conserve l’URL du webhook, donc aucun redéploiement n’est nécessaire.

L’adresse et la clé API sont définies au moment de la création de la connexion et ne peuvent pas être modifiées ensuite. Pour faire pointer Lingo.dev vers une autre adresse ou une autre clé, déconnectez-la puis recréez la connexion.

Déconnecter#

Disconnect en bas de l’onglet Paramètres empêche Lingo.dev de lire depuis l’instance et d’y écrire. Cela supprime la connexion, son historique d’exécution et l’enregistrement de ce qui a été traduit. Les traductions déjà écrites restent dans Payload. Supprimez ensuite LINGO_WEBHOOK_URL ou le plugin de votre configuration.

Limites#

Dépannage#

La connexion échoue avec "Payload rejected the API key". Vérifiez la clé, le slug de la collection d'authentification et que useAPIKey est bien activé sur cette collection.

Une collection ou un global affiche "no read + update". Accordez à l’utilisateur de service les droits de lecture et de mise à jour dans la configuration d’accès de cette collection, puis rechargez la page de connexion. L’interrupteur Sync de la ligne se déverrouillera.

La première exécution échoue avec "The Lingo plugin isn't installed". Ajoutez @lingo.dev/payloadcms au plugins de la configuration Payload puis redéployez. La connexion fonctionne sans le plugin ; la synchronisation, non.

La publication dans Payload ne démarre pas d’exécution. Vérifiez que LINGO_WEBHOOK_URL est défini, que localization est configuré, que la collection ou le global fait partie de la portée, que l’enregistrement a été effectué dans la langue source et qu’il s’agissait d’une publication plutôt que d’un brouillon, sauf si la connexion est en mode Brouillon.

Un champ n’est pas traduit. Il n’a pas localized: true sur lui-même ou sur un parent, ou ce n’est pas un champ text, textarea ou richText.

L’onglet Paramètres affiche la connexion comme Cannot be reached. Vérifiez que l’instance est en ligne, que la clé est toujours valide et que les en-têtes de passerelle fonctionnent toujours. L’adresse et la clé ne peuvent pas être modifiées sur une connexion existante. Si l’une d’elles a changé, déconnectez, reconnectez, puis mettez à jour LINGO_WEBHOOK_URL avec la nouvelle URL du webhook.

Étapes suivantes#