# General Translation Knowledge Base: ¿Cómo traduzco contenido en Payload CMS? URL: https://generaltranslation.com/es/kb/translate-payload-content.mdx Docs index: https://generaltranslation.com/llms.txt Description: Añade localización a tu configuración de Payload y establece localized en true en cada campo; así, Payload almacena un valor por configuración regional, pero no los rellena. El plugin gt-payload de General Translation añade un botón Translate que escribe cada configuración regional de destino como borrador si los borradores están habilitados, o directamente si no lo están. Nunca publica. Category: Herramientas para flujos de trabajo Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Payload CMS almacena las traducciones a nivel de campo. Una vez que tu configuración incluye un bloque `localization`, cada campo marcado con `localized: true` guarda un valor por configuración regional dentro del mismo documento, y tu frontend solicita un idioma mediante el parámetro `locale`. Payload no genera esos valores, y rellenarlos es complicado: el texto enriquecido de Lexical (el editor predeterminado de Payload) contiene enlaces, marcas y bloques incrustados; las listas y los bloques anidan campos localizados; los slugs, las relaciones y los archivos subidos deben quedar intactos; y si un editor corrige una traducción, ese cambio no debería perderse en la siguiente actualización. ## Cómo almacena Payload las traducciones En Payload 3, la localización forma parte de la configuración principal de Payload ([documentación de localización de Payload](https://payloadcms.com/docs/configuration/localization)). Las configuraciones regionales se definen una sola vez: ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; export default buildConfig({ // ... tu configuración existente localization: { locales: ['en', 'es', 'fr'], // u objetos con code, label, rtl y fallbackLocale defaultLocale: 'en', fallback: true, // valor predeterminado: si falta un valor, se usa la configuración regional predeterminada }, }); ``` Después, marca cada campo que quieras traducir. `localized: true` funciona en cualquier campo con nombre, incluidas las listas y los bloques, y los campos anidados dentro de un contenedor localizado pasan a ser conjuntos por configuración regional. Payload advierte que cambiar `localized` en un campo que ya contiene datos hace que se pierdan los datos existentes de ese campo, así que tómalo en cuenta antes de cargar contenido. Todas las API reciben una configuración regional. REST usa `?locale=es` y `?fallback-locale=none`, GraphQL acepta los argumentos `locale` y `fallbackLocale`, y la Local API admite las mismas opciones: ```ts // Valores en español; si un campo no tiene valor en español, se usa el inglés const page = await payload.findByID({ collection: 'pages', id, locale: 'es' }); // Solo valores en español; los campos sin traducir se devuelven vacíos const strict = await payload.findByID({ collection: 'pages', id, locale: 'es', fallbackLocale: false }); // Todas las configuraciones regionales a la vez: all.title es { en: 'Pricing', es: 'Precios' } const all = await payload.findByID({ collection: 'pages', id, locale: 'all' }); ``` En una aplicación de prueba con Payload 3.92, una página que solo tenía títulos en inglés y español devolvió de forma predeterminada el título en inglés para `fr`, y un título vacío con `fallbackLocale: false`. Conviene tener en cuenta este comportamiento predeterminado: una configuración regional sin traducir sirve sin avisar el contenido en el idioma de origen en lugar de fallar. ## Formas de traducir contenido de Payload Los plugins oficiales de Payload incluyen SEO, Redirects, Search e Import/Export, pero ninguno traduce contenido ([plugins de Payload](https://payloadcms.com/docs/plugins/overview)). Estas son las opciones: | Enfoque | Lo que hace bien | Cómo llegan las traducciones a Payload | Lo que queda a tu cargo | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Los editores escriben cada configuración regional | Un traductor ve cada campo en el panel de administración | Cambia la configuración regional del panel de administración y escribe cada valor | Cada traducción, y localizar los campos que cambiaron tras cada edición del origen | | El [plugin Import/Export](https://payloadcms.com/docs/plugins/import-export) de Payload con traductores o un sistema de gestión de traducciones (TMS) | Exporta una configuración regional a CSV o JSON para quienes traducen en archivos | Importa el archivo traducido en la configuración regional de destino | Mantener intactos el texto enriquecido, los bloques y los ID de fila en la exportación y reimportación, y volver a exportar tras cada edición | | Un script sobre una API de IA (OpenAI API, Claude API) | Traduce muchos documentos en una sola ejecución, con tu tono y tu terminología en el prompt | Tu script escribe con `payload.update({ locale })` | Recorrer campos anidados y JSON de Lexical, el contexto de cada cadena, la coherencia terminológica, la revisión y las nuevas ejecuciones | | [Lingo.dev](https://lingo.dev/guides/payload) (`@lingo.dev/payloadcms`) | Traduce automáticamente texto localizado y texto enriquecido al guardar el origen | Su servicio alojado escribe cada configuración regional, ya sea publicada o como borrador | El Plan empresarial de Lingo.dev, un usuario de servicio de Payload con una clave de API y el editor Lexical | | General Translation (`gt-payload`) | Traduce `text`, `textarea` y `richText` de Lexical localizados, incluidos los bloques anidados, con el glosario y los prompts personalizados de tu proyecto | Un botón **Translate** por documento, o una sola ejecución para todo el sitio, escribe cada configuración regional, como borrador si los borradores están habilitados | Iniciar una ejecución tras editar el origen, revisar cada configuración regional y publicar los borradores | Escribe las traducciones a mano cuando tengas pocos documentos y un traductor por idioma. Usa Import/Export cuando una agencia o un TMS ya se encargue de la traducción y trabaje con archivos. Usa un script con una API de IA para un lote puntual que alguien vaya a revisar. Usa General Translation cuando los documentos contengan texto enriquecido y bloques, cambien con frecuencia y deban usar la misma terminología que tu aplicación y tu documentación. (Consulta [General Translation vs. Lingo.dev](/kb/general-translation-vs-lingo-dev) para ver una comparación entre ambos servicios). ## Traducir contenido de Payload con gt-payload El plugin `gt-payload` de General Translation (con licencia MIT, versión 0.1.2) requiere Payload 3.90.0 o posterior con `localization` configurado, Next.js 15.2.9 o posterior, React 19.0.1 o posterior y al menos un campo localizado. 1. Instálalo con `npm install gt-payload`. 2. Agrega el plugin a tu configuración. Como obtiene de Payload tus configuraciones regionales y campos localizados, en la mayoría de los casos no necesita opciones: ```ts title="src/payload.config.ts" import { buildConfig } from 'payload'; import { gtPlugin } from 'gt-payload'; export default buildConfig({ // ... tu configuración existente localization: { locales: ['en', 'es', 'fr'], defaultLocale: 'en', }, plugins: [gtPlugin()], }); ``` 3. Define `GT_PROJECT_ID` y una [clave de API de proyecto](/docs/platform/dashboard/reference/api-keys#create-project-keys) con permisos **All** como `GT_API_KEY` en el servidor donde se ejecuta Payload. Nunca expongas la clave en el código del cliente. 4. Ejecuta `npx payload generate:importmap` para que el panel de administración cargue los componentes del plugin. Si usas PostgreSQL o SQLite, crea y aplica una migración (`npx payload migrate:create` y después `npx payload migrate`) para las dos colecciones que agrega el plugin. 5. Abre un documento guardado, elige **Translate**, selecciona las configuraciones regionales de destino y elige **Translate into …**. Si quieres traducir todo, abre **Traducciones** en la navegación de administración. En una app de prueba con Payload 3.92.1, el plugin agregó al mapa de importaciones y a los tipos generados sus controles de documento, la vista **Traducciones** y las colecciones `gt-translation-runs` y `gt-translation-locks`, y `next build` se completó correctamente. Sus endpoints rechazan cualquier solicitud que no provenga de un usuario de Payload con sesión iniciada. Consulta todos los pasos en el [Inicio rápido de Payload](/docs/integrations/payload/quickstart). ## Qué hace una ejecución de traducción El plugin usa la configuración regional predeterminada como origen y envía el texto localizado de cada documento a tu proyecto de General Translation, donde aparece con su identidad de Payload (`collection/id`, o el slug de un global). Traduce los campos `text` localizados (incluidas las listas `hasMany`), los campos `textarea` y el `richText` de Lexical, también dentro de grupos, pestañas, listas, bloques y bloques de texto enriquecido. El texto enriquecido conserva sus marcas, enlaces, archivos subidos y bloques; si el marcado de una cadena no se puede hacer coincidir con el del origen, esa cadena se omite y se notifica en lugar de escribirse dañada. No toca los campos de slug, los campos de solo lectura, ocultos y virtuales, los valores `text` que parecen URL, rutas o direcciones de correo electrónico, las relaciones, los archivos subidos, las fechas, los números ni los ID. Para omitir un campo, como un SKU, define `custom: { gt: { translate: false } }` en él. Cuando una traducción supera el `maxLength` de un campo, el plugin solicita una más corta y, solo si sigue sin caber, la recorta en un límite de palabra y añade puntos suspensivos. (Consulta [contenido admitido](/docs/integrations/payload/reference/supported-content)). Los resultados se guardan en el mismo documento, en cada configuración regional de destino. Las colecciones y los globales con [borradores](https://payloadcms.com/docs/versions/drafts) reciben un borrador; los demás se guardan directamente. El plugin nunca publica. Las ejecuciones se almacenan en Payload, así que continúan aunque cierres la pestaña: se reanudan en la siguiente visita al panel de administración, o las completa la [cola de trabajos](https://payloadcms.com/docs/jobs-queue/overview) de Payload si `jobs.autoRun` está configurado. Un fallo en un documento o configuración regional no revierte los demás. ## Revisar, publicar y conservar los cambios Revisa cada configuración regional en el editor de Payload y publícala con tus permisos habituales de Payload; los controles del plugin respetan las reglas de acceso del usuario que ha iniciado sesión. Si un editor corrige una traducción en Payload, activa **Save local edits before translating** en el panel **Traducciones** (está desactivado de forma predeterminada) o elige **Save local edits** para que General Translation conserve esa redacción en las siguientes ejecuciones. Al guardar, los valores de Payload pasan a ser la fuente de verdad y reemplazan lo que General Translation tiene almacenado para ese documento. (Consulta [Gestión de traducciones](/docs/integrations/payload/guides/managing-translations)). La calidad de la traducción depende del contexto. Asigna un [grupo de contexto](/docs/platform/dashboard/guides/defining-context-for-translations) al proyecto y su glosario y sus prompts personalizados guiarán cada ejecución de Payload. Así, el nombre de un producto o de un nivel de plan se traducirá igual en las páginas de tu CMS que en tu aplicación. Para traducir desde tu propio código, por ejemplo, desde un hook o un trabajo programado, llama a [`translateDocument`](/docs/integrations/payload/reference/api#translate-document) o a `translateSite` desde `gt-payload`. El uso se factura según los [precios de General Translation](https://generaltranslation.com/pricing). Para el resto de un sitio multilingüe, como las URL por idioma y `hreflang`, consulta [¿Cómo hago que un sitio web sea multilingüe?](/kb/make-website-multilingual). Si usas otro CMS, consulta las guías para [Sanity](/kb/translate-sanity-content) y [Storyblok](/kb/translate-storyblok-content). ## Puntos clave * Payload 3 almacena las traducciones por campo: añade `localization` a la configuración, establece `localized: true` y lee los datos con `locale` y `fallback-locale`. * Con el valor predeterminado `fallback: true`, una configuración regional que no hayas traducido muestra el texto de origen, así que comprueba la cobertura antes de enlazar un idioma. * Payload no tiene un plugin de traducción oficial; su plugin Import/Export permite exportar una configuración regional en formato CSV o JSON para enviarla a los traductores. * `gt-payload` de General Translation añade `gtPlugin()`, un botón **Translate** y una página **Traducciones** para todo el sitio. Traduce campos localizados de tipo text, textarea y texto enriquecido de Lexical, y guarda cada configuración regional como borrador cuando los borradores están habilitados, sin publicar nunca. * Activa **Save local edits before translating** para que los cambios realizados en Payload no se pierdan en ejecuciones posteriores. ## Related questions - [¿Cómo traduzco contenido en Sanity?](https://generaltranslation.com/es/kb/translate-sanity-content.mdx): Almacena cada idioma como un documento propio o como un valor por configuración regional en cada campo y, después, traduce el origen a cada configuración regional de destino. El plugin gt-sanity de General Translation añade una acción Translate a Sanity Studio y, de forma predeterminada, importa cada traducción como un borrador para que lo revises y lo publiques. - [¿Cómo traduzco contenido en Storyblok?](https://generaltranslation.com/es/kb/translate-storyblok-content.mdx): En Storyblok, agrega tus idiomas de destino al espacio y asigna a cada campo traducible un valor por idioma. La integración de Storyblok de General Translation rellena esos valores desde el panel de control con Sincronizar y aplicar, como borradores que luego revisas y publicas en Storyblok. - [¿Cómo hago que un sitio web sea multilingüe?](https://generaltranslation.com/es/kb/make-website-multilingual.mdx): Elige dónde se alojarán las traducciones (en un proxy, un plugin de CMS, un creador de sitios web o tu propio código) y después asigna a cada idioma su propia URL, tal como recomienda Google. Traduce las páginas completas, además de los títulos y las metadescripciones, vincula las versiones con hreflang y ofrece un selector de idioma en lugar de redirigir automáticamente a los visitantes. - [¿Cómo reviso y edito traducciones?](https://generaltranslation.com/es/kb/review-translations.mdx): Compara cada traducción con su texto de origen y con las demás configuraciones regionales, y corrige lo que no suene bien. Con General Translation, editas las traducciones en la Página de traducciones del panel de control y haces seguimiento de la revisión con etiquetas y comentarios. Después, la siguiente ejecución de traducción de Locadex, su Agente de IA, incorpora los cambios en un pull request. - [General Translation vs. Lingo.dev: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-lingo-dev.mdx): Lingo.dev gira en torno a motores de traducción configurables, con herramientas de CLI, React y GitHub para acceder a ellos. General Translation es una plataforma de localización: bibliotecas, contexto del código, terminología compartida, revisión en el panel de control en todos los planes y Locadex, que además internacionaliza tu código. Elige Lingo.dev si quieres controlar el modelo por par de idiomas. ## Previous and next questions - Previous question: [¿Cómo traduzco archivos PO y POT?](https://generaltranslation.com/es/kb/translate-po-files.mdx) - Next question: [¿Cómo traduzco los títulos SEO y las metadescripciones?](https://generaltranslation.com/es/kb/translate-seo-metadata.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.