# General Translation Knowledge Base: Comment traduire du contenu dans Payload CMS ? URL: https://generaltranslation.com/fr/kb/translate-payload-content.mdx Docs index: https://generaltranslation.com/llms.txt Description: Ajoutez la localisation à votre configuration Payload et définissez localized sur true pour chaque champ ; Payload stocke alors une valeur par paramètre régional, mais ne les remplit pas. Le plugin gt-payload de General Translation ajoute un bouton Traduire qui renseigne chaque locale cible, sous forme de brouillon si les brouillons sont activés, et directement dans le cas contraire. Il ne publie jamais. Category: Outils de workflow Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Payload CMS stocke les traductions au niveau des champs. Dès que votre configuration contient un bloc `localization`, chaque champ marqué `localized: true` contient une valeur par paramètre régional au sein du même document, et votre frontend demande une langue via le paramètre `locale`. Payload ne génère pas ces valeurs, et les renseigner s’avère délicat : le texte enrichi Lexical (l’éditeur par défaut de Payload) comporte des liens, des marques et des blocs intégrés ; les tableaux et les blocs contiennent des champs localisés imbriqués ; les slugs, les relations et les fichiers téléversés doivent rester tels quels ; et une correction apportée à une traduction par un éditeur ne doit pas être écrasée lors de la mise à jour suivante. ## Comment Payload stocke les traductions Dans Payload 3, la localisation fait partie intégrante de la configuration principale de Payload ([documentation de Payload sur la localisation](https://payloadcms.com/docs/configuration/localization)). Il suffit de déclarer les paramètres régionaux une seule fois : ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; export default buildConfig({ // ... votre configuration existante localization: { locales: ['en', 'es', 'fr'], // ou des objets avec code, label, rtl et fallbackLocale defaultLocale: 'en', fallback: true, // comportement par défaut : une valeur manquante est remplacée par celle des paramètres régionaux par défaut }, }); ``` Marquez ensuite chaque champ à traduire. `localized: true` s'applique à n'importe quel champ nommé, y compris les tableaux et les blocs, et les champs imbriqués dans un conteneur localisé deviennent des ensembles distincts par paramètre régional. Payload prévient que modifier `localized` sur un champ qui contient déjà des données entraîne la perte des données existantes de ce champ : faites donc ce choix avant de charger du contenu. Chaque API accepte un paramètre régional. REST utilise `?locale=es` et `?fallback-locale=none`, GraphQL accepte les arguments `locale` et `fallbackLocale`, et la Local API accepte les mêmes options : ```ts // Valeurs en espagnol, avec repli sur l'anglais pour les champs sans valeur espagnole const page = await payload.findByID({ collection: 'pages', id, locale: 'es' }); // Valeurs en espagnol uniquement ; les champs non traduits sont renvoyés vides const strict = await payload.findByID({ collection: 'pages', id, locale: 'es', fallbackLocale: false }); // Tous les paramètres régionaux d'un coup : all.title vaut { en: 'Pricing', es: 'Precios' } const all = await payload.findByID({ collection: 'pages', id, locale: 'all' }); ``` Dans une application de test sous Payload 3.92, une page disposant uniquement de titres en anglais et en espagnol renvoyait par défaut le titre anglais pour `fr`, et un titre vide avec `fallbackLocale: false`. Ce comportement par défaut est bon à savoir : un paramètre régional non traduit renvoie discrètement la langue source au lieu de générer une erreur. ## Méthodes pour traduire du contenu Payload Les plugins officiels de Payload comprennent SEO, Redirects, Search et Import/Export, mais aucun ne traduit le contenu ([plugins Payload](https://payloadcms.com/docs/plugins/overview)). Voici les options possibles : | Approche | Points forts | Comment les traductions arrivent dans Payload | Ce qui reste à votre charge | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Les éditeurs saisissent chaque paramètre régional | Un traducteur voit chaque champ dans le panneau d’administration | Changer le paramètre régional de l’administration et saisir chaque valeur | Chaque traduction, ainsi que le repérage des champs modifiés après chaque modification de la source | | Le [plugin Import/Export](https://payloadcms.com/docs/plugins/import-export) de Payload avec des traducteurs ou un système de gestion de la traduction (TMS) | Exporte un paramètre régional en CSV ou JSON pour les personnes qui traduisent dans des fichiers | Importer le fichier traduit dans la locale cible | Préserver le texte enrichi, les blocs et les identifiants de lignes tout au long de l’aller-retour, et réexporter après chaque modification | | Un script s’appuyant sur une API d’IA (OpenAI API, Claude API) | Traduit de nombreux documents en une seule exécution, avec votre ton et votre terminologie définis dans l’instruction | Votre script écrit via `payload.update({ locale })` | Le parcours des champs imbriqués et du JSON Lexical, le contexte de chaque chaîne de caractères, la cohérence terminologique, la relecture et les réexécutions | | [Lingo.dev](https://lingo.dev/guides/payload) (`@lingo.dev/payloadcms`) | Traduit automatiquement le texte localisé et le texte enrichi à l’enregistrement de la source | Son service hébergé écrit chaque paramètre régional, publié ou en brouillon | L’offre Enterprise de Lingo.dev, un utilisateur de service Payload doté d’une clé API, et l’éditeur Lexical | | General Translation (`gt-payload`) | Traduit les champs localisés `text`, `textarea` et `richText` Lexical, blocs imbriqués compris, en appliquant le glossaire et les instructions personnalisées de votre projet | Un bouton **Traduire** par document, ou une seule exécution pour tout le site, écrit chaque paramètre régional, en brouillon lorsque les brouillons sont activés | Lancer une exécution après chaque modification de la source, relire chaque paramètre régional et publier les brouillons | Saisissez les traductions à la main si vous avez peu de documents et un traducteur par langue. Optez pour Import/Export lorsqu’une agence ou un TMS gère déjà la traduction et travaille sur des fichiers. Privilégiez un script basé sur une API d’IA pour un lot ponctuel qui sera relu par quelqu’un. Choisissez General Translation lorsque vos documents contiennent du texte enrichi et des blocs, changent souvent et doivent employer la même terminologie que votre application et votre documentation. (Consultez [General Translation vs. Lingo.dev](/kb/general-translation-vs-lingo-dev) pour une comparaison des deux services.) ## Traduire le contenu Payload avec gt-payload Le plugin `gt-payload` de General Translation (sous licence MIT, version 0.1.2) nécessite Payload 3.90.0 ou version ultérieure avec `localization` configuré, Next.js 15.2.9 ou version ultérieure, React 19.0.1 ou version ultérieure, ainsi qu'au moins un champ localisé. 1. Installez-le avec `npm install gt-payload`. 2. Ajoutez le plugin à votre configuration. Il récupère vos paramètres régionaux et vos champs localisés depuis Payload : dans la plupart des cas, il n'a donc besoin d'aucune option : ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; import { gtPlugin } from 'gt-payload'; export default buildConfig({ // ... votre configuration existante localization: { locales: ['en', 'es', 'fr'], defaultLocale: 'en', }, plugins: [gtPlugin()], }); ``` 3. Sur le serveur qui exécute Payload, définissez `GT_PROJECT_ID` ainsi que `GT_API_KEY`, qui doit contenir une [clé API de projet](/docs/platform/dashboard/reference/api-keys#create-project-keys) disposant de toutes les autorisations (**All**). N'exposez jamais la clé au code client. 4. Exécutez `npx payload generate:importmap` pour que le panneau d'administration charge les composants du plugin. Avec PostgreSQL ou SQLite, créez puis appliquez une migration (`npx payload migrate:create`, puis `npx payload migrate`) pour les deux collections ajoutées par le plugin. 5. Ouvrez un document enregistré, choisissez **Traduire**, sélectionnez les paramètres régionaux cibles, puis choisissez **Traduire en …**. Pour tout traduire d'un coup, ouvrez plutôt **Translations** dans la navigation de l'administration. Dans une application de test sous Payload 3.92.1, le plugin a bien ajouté ses contrôles de document, la vue **Translations** ainsi que les collections `gt-translation-runs` et `gt-translation-locks` à l'import map et aux types générés, et `next build` s'est exécuté sans erreur. Ses points de terminaison rejettent toute requête provenant d'un utilisateur non connecté à Payload. Consultez le [Démarrage rapide Payload](/docs/integrations/payload/quickstart) pour la procédure complète. ## Ce que fait une exécution de traduction Le plugin utilise les paramètres régionaux par défaut comme source et envoie le texte localisé de chaque document à votre projet General Translation, où il apparaît sous son identité Payload (`collection/id`, ou le slug d’un global). Il traduit les champs `text` localisés (y compris les listes `hasMany`), les champs `textarea` et le `richText` Lexical, y compris à l’intérieur des groupes, onglets, tableaux, blocs et blocs de texte enrichi. Le texte enrichi conserve ses marques, liens, fichiers téléversés et blocs ; une chaîne de caractères dont le balisage ne correspond pas à celui de la source est ignorée et signalée, plutôt qu’écrite sous une forme corrompue. Il laisse de côté les champs slug, les champs en lecture seule, masqués et virtuels, les valeurs `text` qui ressemblent à des URL, des chemins ou des adresses e-mail, ainsi que les relations, fichiers téléversés, dates, nombres et ID. Pour ignorer un champ, comme un SKU, définissez `custom: { gt: { translate: false } }` sur celui-ci. Lorsqu’une traduction dépasse la `maxLength` d’un champ, le plugin en demande une plus courte, et ne la tronque à une limite de mot avec des points de suspension que si elle reste trop longue. (Voir [contenu pris en charge](/docs/integrations/payload/reference/supported-content).) Les résultats sont enregistrés dans le même document, sous chaque locale cible. Les collections et globals pour lesquels les [brouillons](https://payloadcms.com/docs/versions/drafts) sont activés reçoivent un brouillon ; les autres sont enregistrés directement. Le plugin ne publie jamais. Les exécutions étant stockées dans Payload, elles se poursuivent même après la fermeture de l’onglet : elles reprennent lors de la prochaine visite de l’interface d’administration, ou la [file de tâches](https://payloadcms.com/docs/jobs-queue/overview) de Payload les mène à terme lorsque `jobs.autoRun` est configuré. Un échec sur un document ou un paramètre régional n’annule pas les autres. ## Relire, publier et conserver les modifications Relisez chaque paramètre régional dans l'éditeur de Payload et publiez-le avec vos autorisations Payload habituelles ; les contrôles du plugin respectent les règles d'accès de l'utilisateur connecté. Si un éditeur corrige une traduction dans Payload, activez **Save local edits before translating** dans le panneau **Translations** (désactivé par défaut) ou choisissez **Save local edits**, afin que General Translation conserve cette formulation lors des exécutions suivantes. L'enregistrement fait des valeurs de Payload la source de vérité et remplace ce que General Translation détient pour ce document. (Voir [Gestion des traductions](/docs/integrations/payload/guides/managing-translations).) La qualité d'une traduction repose sur le contexte. Attribuez un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) au projet : son glossaire et ses instructions personnalisées guident chaque exécution Payload, de sorte qu'un nom de produit ou un niveau d'offre soit traduit de la même façon dans les pages de votre CMS que dans votre application. Pour lancer une traduction depuis votre propre code, par exemple depuis un hook ou une tâche planifiée, appelez [`translateDocument`](/docs/integrations/payload/reference/api#translate-document) ou `translateSite` depuis `gt-payload`. L'utilisation est facturée selon les [tarifs de General Translation](https://generaltranslation.com/pricing). Pour les autres aspects d'un site multilingue, comme les URL par langue et `hreflang`, consultez [Comment rendre un site web multilingue ?](/kb/make-website-multilingual). La même procédure est également décrite pour d'autres CMS : [Sanity](/kb/translate-sanity-content) et [Storyblok](/kb/translate-storyblok-content). ## Points clés * Payload 3 stocke les traductions par champ : ajoutez `localization` à la configuration, définissez `localized: true`, puis lisez les données avec `locale` et `fallback-locale`. * Avec la valeur par défaut `fallback: true`, un paramètre régional que vous n'avez pas traduit renvoie le texte source ; vérifiez donc la couverture avant d'ajouter un lien vers une langue. * Payload ne propose aucun plugin de traduction officiel ; son plugin Import/Export permet toutefois d'exporter un paramètre régional au format CSV ou JSON pour le confier à des traducteurs. * Le paquet `gt-payload` de General Translation ajoute `gtPlugin()`, un bouton **Traduire** et une page **Translations** commune à tout le site ; il traduit les champs localisés de type text, textarea et texte enrichi Lexical, et enregistre chaque paramètre régional en tant que brouillon lorsque les brouillons sont activés, sans jamais rien publier. * Activez **Save local edits before translating** pour que les modifications effectuées dans Payload ne soient pas écrasées lors des exécutions suivantes. ## Related questions - [Comment traduire du contenu dans Sanity ?](https://generaltranslation.com/fr/kb/translate-sanity-content.mdx): Stockez chaque langue dans son propre document ou sous forme de valeur par paramètre régional dans chaque champ, puis traduisez la source dans chaque paramètre régional cible. Le plugin gt-sanity de General Translation ajoute une action Translate à Sanity Studio et, par défaut, importe chaque traduction sous forme de brouillon, que vous relisez puis publiez. - [Comment traduire du contenu dans Storyblok ?](https://generaltranslation.com/fr/kb/translate-storyblok-content.mdx): Dans Storyblok, ajoutez vos langues cibles à l’espace et attribuez à chaque champ traduisible une valeur par langue. L’intégration Storyblok de General Translation remplit ces valeurs depuis le tableau de bord grâce à Synchroniser et appliquer, sous forme de brouillons que vous relisez et publiez dans Storyblok. - [Comment rendre un site web multilingue ?](https://generaltranslation.com/fr/kb/make-website-multilingual.mdx): Choisissez où stocker les traductions (dans un proxy, un plugin de CMS, un constructeur de sites ou votre propre code), puis attribuez à chaque langue sa propre URL, comme le recommande Google. Traduisez les pages entières ainsi que les titres et les méta-descriptions, reliez les versions avec hreflang et proposez un sélecteur de langue plutôt que de rediriger automatiquement les visiteurs. - [Comment relire et modifier les traductions ?](https://generaltranslation.com/fr/kb/review-translations.mdx): Comparez chaque traduction avec sa source et les autres paramètres régionaux, puis corrigez ce qui sonne faux. Avec General Translation, vous modifiez les traductions sur la page Translations du tableau de bord et suivez la relecture à l’aide d’étiquettes et de commentaires ; la prochaine exécution de traduction de Locadex, son agent IA, intègre ensuite vos modifications dans une pull request. - [General Translation ou Lingo.dev : lequel choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-lingo-dev.mdx): Lingo.dev repose sur des moteurs de traduction configurables, accessibles via des outils CLI, React et GitHub. General Translation est une plateforme de localisation : bibliothèques, contexte du code, terminologie partagée, relecture dans le tableau de bord incluse dans toutes les offres, et Locadex, qui internationalise aussi votre code. Choisissez Lingo.dev si vous voulez contrôler le modèle pour chaque paire de langues. ## Previous and next questions - Previous question: [Comment traduire des fichiers PO et POT ?](https://generaltranslation.com/fr/kb/translate-po-files.mdx) - Next question: [Comment traduire les fichiers .resx dans une application .NET ?](https://generaltranslation.com/fr/kb/translate-resx-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.