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.
L’intégration Payload s’active au niveau de l’organisation. Si vous ne la voyez pas dans Settings -> Integrations, contactez-nous et nous l’activerons pour vous.
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: truesur votre collection d'authentification (généralementusers), 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.
Les codes de langue doivent correspondre à votre configuration Payload
Les langues que vous choisissez dans Lingo.dev doivent correspondre exactement aux codes définis dans localization.locales. Si Payload utilise en et de, choisissez anglais et allemand, pas anglais (États-Unis) : en-US et en sont des langues différentes. Utilisez votre defaultLocale Payload comme langue source, car c'est celle que le plugin surveille pour détecter les changements.
Connectez votre instance Payload#
Ouvrez l’intégration
Rendez-vous dans Settings -> Integrations et cliquez sur Connect sous Payload CMS.
Renseignez les détails de votre instance
| Champ | Valeur à saisir |
|---|---|
| Nom de la connexion | Un libellé comme Production ou Staging |
| URL de base Payload | L’URL racine de votre instance, par ex. https://cms.example.com. HTTPS uniquement |
| Slug de la collection d’authentification | La collection à laquelle appartient la clé API de votre utilisateur de service, généralement users |
| Clé API | La clé API de l'utilisateur de service |
| En-têtes personnalisés | Facultatif. Envoyé avec chaque requête à votre instance. |
Lingo.dev vérifie la clé auprès de votre instance avant de passer à l'étape suivante.
Choisissez quoi traduire
| Paramètre | Rôle |
|---|---|
| Collections et Globals | Cochez les éléments à traduire. Une ligne marquée No read + update reste désactivée tant que l’utilisateur de service n’y a pas accès |
| Langue source | La langue dans laquelle vos équipes éditoriales rédigent. Utilisez votre defaultLocale Payload |
| Langues cibles | Les langues dans lesquelles traduire |
| Moteur | Le moteur de localisation qui traduit ce contenu |
| Traduire les sauvegardes de brouillon | Désactivé : seuls les changements publiés sont traduits. Activé : les sauvegardes de brouillons sont aussi traduites et les traductions restent en brouillon |
Installez le plugin
La dernière étape affiche votre URL de webhook. Copiez-la maintenant. Elle ne s'affiche qu'une seule fois. Enregistrez-la sous LINGO_WEBHOOK_URL dans votre environnement Payload, puis installez le plugin et ajoutez-le à votre configuration :
pnpm add @lingo.dev/payloadcmsimport { 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,
}),
],
});Redéployez Payload. Désormais, chaque modification publiée dans la langue source est envoyée à Lingo.dev pour traduction.
Ce que fait le plugin
Cela ajoute un endpoint GET /api/lingo/schema qui indique à Lingo.dev lesquels de vos champs sont du texte localisé, ainsi qu'un hook qui notifie Lingo.dev lorsqu'un document ou un global change. La portée, les langues et le moteur se gèrent depuis le tableau de bord, ce qui vous permet de les modifier sans redéployer. Omettez webhookUrl pour désactiver le hook et lancer chaque traduction depuis le tableau de bord.
Choisissez ce qui est traduit#
La page de connexion comporte trois onglets : Collections, Globals et Runs.
La portée se définit par collection et par global. Tous les documents d'une collection sélectionnée sont inclus. Pour modifier la portée, les langues, le moteur ou le réglage des brouillons, cliquez sur Modifier la configuration dans l'en-tête de la page. Les changements s'appliquent dès la prochaine exécution, sans redéploiement.
Dans un document, c’est la configuration des champs Payload qui détermine ce qui est traduit :
| Champ | Traduit |
|---|---|
Champs text, textarea et richText marqués localized: true | Oui |
Les mêmes types de champs à l’intérieur d’un group, array, blocks ou tabs localisé | Oui |
| Blocs et blocs en ligne intégrés dans le texte enrichi | Oui, leurs champs de texte suivent les mêmes règles |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | Non |
| Champs non localisés sans parent localisé | Non |
id, blockType, blockName | Non |
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. Une fois webhookUrl configuré dans le plugin, chaque enregistrement d’un document ou d’un global dans la langue source envoie une notification à Lingo.dev. Les enregistrements effectués à quelques instants d’intervalle sont regroupés en une seule exécution. Les enregistrements dans d’autres langues, les brouillons enregistrés (sauf si Traduire les enregistrements de brouillons est activé) et les contenus hors de votre périmètre sont ignorés.
Exécutions manuelles. Chaque ligne de collection, de global et de document propose deux boutons :
| Bouton | Rôle | Quand l’utiliser |
|---|---|---|
| Sync | Traduit uniquement ce qui a changé depuis la dernière exécution | Préremplir le contenu après la connexion, ou relancer après un échec |
| Retranslate | Traduit à nouveau tout le contenu de la ligne, depuis zéro | Après avoir modifié le glossaire, la voix de marque ou les règles de votre moteur |
Ouvrez une collection pour accéder à ses documents et les synchroniser un par un. Les deux onglets indiquent la date de dernière synchronisation de chaque élément.
Rien n'est traduit au moment de la connexion. Pour traduire votre contenu existant, cliquez sur Sync pour chaque collection et global. Ajouter une langue cible plus tard fonctionne de la même manière : le prochain Sync la renseignera.
Une seule exécution peut être en cours à la fois par connexion. Les demandes supplémentaires sont mises en file d'attente et démarrent dans l'ordre. Lorsqu'une ligne est concernée par une exécution en attente ou en cours, ses boutons affichent Syncing....
Retranslate écrase les retouches manuelles
Retranslate régénère chaque champ traduit dans sa portée, y compris les traductions que votre équipe a modifiées manuellement dans Payload. Sync, lui, ne régénère que les champs dont le texte source a changé, ce qui préserve les modifications manuelles ailleurs.
Suivre une exécution#
L'onglet Runs répertorie chaque exécution avec son statut, son déclencheur (Webhook ou Manual, sync ou retranslate), son heure de début et sa durée. Une exécution en attente ou en cours peut être annulée depuis la liste.
Ouvrez une exécution pour voir son étape en cours (lecture depuis Payload, traduction, réécriture), la progression globale, la progression par langue cible, ainsi que les documents, collections et globals qu'elle couvre. Chaque élément renvoie vers l'administration Payload.
| Statut | Signification |
|---|---|
| En file d’attente | En attente de l'exécution qui la précède |
| En cours | Traitement en cours |
| Terminée | Toutes les traductions ont été réécrites |
| À jour | Rien dans la portée n'a changé depuis la dernière exécution. Ce n'est pas un échec |
| Échouée | L’exécution s’est arrêtée. La raison s’affiche en haut du détail de l’exécution |
| Annulée | Arrêtée par une personne de votre équipe |
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#
Lorsque Translate draft saves est désactivé (par défaut), seules les modifications publiées lancent une exécution, et les traductions sont publiées dès qu’elles sont écrites. Payload publie l’intégralité du document : toute modification de brouillon non publiée qu’il contient est donc mise en ligne avec la traduction.
Lorsque ce réglage est activé, les sauvegardes de brouillons déclenchent elles aussi des exécutions. Lingo.dev lit le dernier brouillon de la source et écrit chaque traduction en brouillon. Rien ne change pour vos lecteurs et lectrices tant que quelqu'un ne publie pas la traduction dans Payload. Utilisez ce mode pendant l'évaluation de la qualité des traductions ou lorsque les traductions passent par une relecture.
Gérer la connexion#
Renouveler l'URL du webhook#
Ouvrez le menu dans l’en-tête de la page de connexion, puis choisissez Régénérer l’URL du webhook. L’ancienne URL cesse de fonctionner immédiatement. Mettez à jour LINGO_WEBHOOK_URL et redéployez. Modifier la connexion conserve l’URL.
Déconnecter#
Déconnectez-vous depuis Settings -> Integrations -> Payload CMS. Cela supprime la connexion, son historique d'exécutions et l'enregistrement de ce qui a été traduit. Les traductions déjà écrites restent dans Payload. Supprimez ensuite LINGO_WEBHOOK_URL ou retirez le plugin de votre configuration.
Se reconnecter signifie obtenir une nouvelle URL de webhook
Une nouvelle connexion reçoit une nouvelle URL de webhook. Mettez donc à jour LINGO_WEBHOOK_URL et redéployez avant que les exécutions automatiques ne refonctionnent. La première synchronisation relit chaque document dans la portée, conserve les traductions déjà présentes dans Payload et comble les champs manquants.
Limites#
| Limite | Détail |
|---|---|
| Version de Payload | Payload 3 avec la localisation configurée |
| Types de champs | Champs text, textarea et richText (Lexical uniquement) marqués localized |
| Portée | Collections et globals entiers. Aucune sélection champ par champ |
| Connexions | Plusieurs par organisation, une par instance Payload |
| Exécutions simultanées | Une par connexion |
| URL de base | HTTPS uniquement |
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 rouvrez la configuration.
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éclenche pas d'exécution. Vérifiez que LINGO_WEBHOOK_URL est bien défini, que localization est configuré, que la collection ou le global est dans la portée, que l'enregistrement a eu lieu dans la langue source et qu'il s'agissait bien d'une publication, et non d'un 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.
La connexion affiche "Couldn't reach this Payload instance". Vérifiez que l'instance est bien en ligne, que la clé est toujours valide et que les en-têtes de passerelle fonctionnent encore. Mettez à jour la connexion dans Settings -> Integrations.
