Payload CMS
Traduce los campos localizados de Payload 3, conserva la estructura de los recursos y decide cómo llegan los cambios del contenido de origen a los idiomas de destino.
Payload ya reserva un espacio en cada campo localizado para sus versiones en distintos idiomas. La conexión de Lingo.dev lee los campos de origen seleccionados, los traduce mediante un motor de localización y guarda los resultados en esos mismos recursos, en los idiomas de destino. Las colecciones, los recursos globales y la publicación siguen gestionándose en Payload.
En el menú de navegación de Studio 2.5, abre Studio 2.5 → Integraciones en lugar de Configuración → Integraciones. Los enlaces de conexión y configuración que ya tienes siguen funcionando.
Empieza con un solo recurso y una sincronización manual. Tras comprobar el resultado, añade notificaciones de cambios en el contenido de origen si quieres que la traducción se actualice automáticamente al editarlo.
La integración con Payload CMS está disponible con el plan Enterprise. Consulta los precios para conocer la disponibilidad actual. En Configuración → Integraciones aparece No disponible en tu plan junto a Payload cuando la organización necesita un plan que dé acceso a la integración.
Prepara Payload y un usuario de servicio #
Utiliza Payload 3 con la localización configurada. La traducción de texto enriquecido es compatible con el editor Lexical, pero no con el antiguo editor Slate. Lingo.dev debe poder acceder a tu instancia mediante HTTPS.
Crea un usuario de servicio en una colección de autenticación con useAPIKey: true, normalmente users. Concede a ese usuario acceso de lectura y actualización a todas las colecciones o recursos globales que quieras traducir. Las escrituras se atribuyen a este usuario. Si una pasarela requiere cabeceras adicionales, facilítalas al conectar y mantén sus valores en secreto.
Configura el idioma de origen de la conexión para que coincida con localization.defaultLocale de Payload, que es el idioma cuyos cambios supervisa el complemento. Los códigos de origen y destino deben coincidir exactamente con los configurados en Payload: en y en-US identifican idiomas distintos. Elige un motor de localización al que tengas acceso en la organización de Lingo.dev conectada. Si no puedes añadir la conexión, comprueba los permisos de tu organización y si tiene habilitado el acceso a las conexiones.
Conecta la instancia y expón su esquema #
Abre Configuración → Integraciones y selecciona Conectar para Payload CMS. Introduce un nombre para la conexión, la dirección raíz de la instancia, la colección de autenticación, la clave de API del usuario de servicio y las cabeceras de la pasarela, si las hay. Selecciona Conectar para verificar el acceso y guardar la conexión. Conserva la URL del webhook que aparece a continuación para las notificaciones automáticas.
Instala el complemento en el proyecto de Payload:
pnpm add @lingo.dev/payloadcmsAñade lingo al array plugins existente. Este fragmento muestra la configuración del complemento; conserva las colecciones, los recursos globales, la localización y los demás complementos de tu proyecto:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
plugins: [
lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
],
});El complemento siempre registra GET /api/lingo/schema. Lingo.dev utiliza este punto de acceso para identificar los campos localizados. Puedes crear una conexión antes de instalar el complemento, pero para traducir es necesario que el punto de acceso del esquema esté disponible.
Para recibir notificaciones automáticas, copia la URL del webhook de la conexión en la variable de entorno LINGO_WEBHOOK_URL de Payload. Trátala como una credencial secreta: cualquiera que disponga de la URL puede enviar solicitudes de notificación. Vuelve a desplegar Payload después de cambiar el complemento o el entorno. Para traducir solo de forma manual, omite webhookUrl; el complemento seguirá exponiendo el esquema.
En Studio, selecciona la instancia en Conectadas y, después, Configurar. Elige su motor de localización, los idiomas de origen y destino y el modo de escritura de los resultados. Selecciona Continuar y elige las colecciones y los recursos globales que quieras traducir. Los modos de publicación se describen a continuación.
Traduce un recurso #
Elige una colección o un recurso global que contenga un campo localizado con un texto breve y selecciona un idioma de destino. Anota sus valores actuales de origen y destino en Payload antes de ejecutar la sincronización.
Selecciona el modo según el resultado de publicación que busques:
| Modo | Origen y escritura de resultados |
|---|---|
| Borrador | Lee el contenido de origen en borrador y guarda los campos traducidos como borradores para su revisión en Payload. |
| Publicar | Procesa los cambios publicados y guarda las traducciones como publicadas. |
Payload mantiene un único borrador compartido por documento y lo publica por completo. Por eso, guardar una traducción en un documento publicado que tenga cambios pendientes de publicar también publicaría esos cambios. En estos casos, el modo Publicar deja el documento sin cambios y marca su traducción como fallida. Publica los cambios o restaura la versión publicada en Payload y, después, vuelve a ejecutar Sincronizar. Para ver esos cambios, el usuario asociado a la clave de API necesita acceso readVersions a todas las versiones de las colecciones y los elementos globales seleccionados; si ese acceso está filtrado, el modo Publicar deja sus documentos publicados sin cambios. Si un documento nunca se ha publicado, se omite esta comprobación: el modo Publicar guarda la traducción en él y el documento sigue siendo un borrador. La comprobación se realiza justo antes de cada escritura, por lo que un borrador guardado entre la comprobación y la escritura podría publicarse junto con la traducción. Evita guardar borradores de documentos mientras una sincronización esté escribiendo en ellos y comprueba después su estado de publicación. El comportamiento de los borradores también depende de tu configuración de Payload; al probar una actualización, comprueba la versión que está publicada en ese momento.
Ejecuta Sincronizar, abre la ejecución del flujo de trabajo correspondiente y revisa el campo de destino en Payload. Comprueba la redacción, los enlaces, la estructura del texto enriquecido, el idioma y el estado de publicación. Después, lee el contenido en el sitio que lo utiliza. Conectar la instancia no basta para traducir el catálogo.
La primera sincronización conserva las traducciones existentes que estén completas, sin sustituirlas. Rellena los campos que faltan, incluidos aquellos cuyo valor actual se limita a repetir el valor predeterminado de Payload. Si se ha conservado un campo, compara su valor con ese estado antes de solicitar que se sustituya.
Selecciona recursos y campos #
Las tablas Colecciones y Recursos globales tienen interruptores de Sincronizar cuya selección se conserva. Seleccionar una colección incluye sus documentos; seleccionar un recurso global incluye ese recurso. Las acciones de la cabecera procesan los recursos habilitados. Cuando hay acciones para las filas seleccionadas, estas ponen en cola únicamente lo seleccionado, sin modificar la selección persistente de la conexión.
Dentro de esos recursos, el esquema selecciona los campos localizados text, textarea y richText de Lexical. También recorre el texto de los grupos, arrays, bloques y pestañas localizados, incluidos los bloques de texto enriquecido anidados y en línea.
Los campos no localizados y los valores estructurales, como id, blockType y blockName, quedan fuera del texto que se traduce. Los campos de selección, los números, las relaciones, los archivos subidos, el código y el JSON arbitrario no pasan a ser traducibles por el mero hecho de seleccionar su colección. Para incluir otro campo de texto, configura su localización en Payload y vuelve a desplegar el proyecto.
El procesamiento de Lexical conserva el contexto de las frases a través del formato en línea y los enlaces, y después reconstruye el árbol con sus enlaces, elementos multimedia y bloques. Prueba un documento representativo antes de ampliar el ámbito, sobre todo si tu proyecto utiliza campos personalizados o extensiones del editor.
Mantén las traducciones al día con los cambios del contenido de origen #
Con una URL de webhook y un idioma predeterminado configurados, el complemento envía notificaciones tras los cambios en el idioma de origen. Cada notificación contiene una referencia al recurso, no el cuerpo del documento. Lingo.dev vuelve a leer el contenido con las credenciales de servicio guardadas, aplica el ámbito y el modo de la conexión y agrupa las notificaciones cercanas en el tiempo antes de procesarlas.
Las escrituras en el idioma de destino no activan otra traducción. Los fallos en las notificaciones tampoco impiden guardar los cambios en el editor, así que un guardado correcto no basta para confirmar la entrega de la notificación. Si se ha pasado por alto un cambio, revisa el historial de ejecuciones y utiliza una sincronización manual para poner el contenido al día. Guardar borradores sí cuenta en el modo Borrador; guardar en un idioma de destino o en un recurso fuera del ámbito no constituye un cambio de origen para esta conexión.
Utiliza Sincronizar para procesar los cambios del contenido de origen y completar el contenido de destino que falte. Esta acción compara el contenido con la referencia de partida disponible. Cuando no está disponible un artefacto de origen anterior, la recuperación puede regenerar el contenido afectado, así que revisa las diferencias en lugar de dar por hecho que se conservarán todas las modificaciones manuales. Tras añadir un idioma de destino, ejecuta una sincronización para completarlo.
Utiliza Volver a traducir cuando quieras sustituir las traducciones seleccionadas, incluidos los campos editados manualmente. Por ejemplo, un cambio importante en las instrucciones del motor de localización puede justificar un nuevo resultado aunque el contenido de origen no haya cambiado. Las solicitudes se ponen en cola detrás de la ejecución activa de la conexión; enviar la misma acción varias veces no hace que termine antes.
Recupera un documento modificado o escrito parcialmente #
El paso de escritura de resultados vuelve a leer el contenido de origen. Si alguien lo ha modificado en el editor después de la planificación, el documento se omite para no aplicar los valores traducidos a una revisión distinta o a un array con otro orden. Una sincronización posterior pone al día las traducciones con el nuevo contenido de origen.
Las ejecuciones fallidas o canceladas conservan las escrituras realizadas correctamente. En Ejecuciones de flujos de trabajo, distingue entre el trabajo completado, actualizado, omitido, fallido y cancelado, y revisa los recursos afectados antes de volver a intentarlo. Detener cancela el trabajo activo cuando la acción está disponible; no revierte los campos ya escritos. Un resultado actualizado significa que no había ningún cambio seleccionado que procesar.
Si el resultado no aparece, comprueba el punto de acceso del esquema, la localización y el tipo del campo, los permisos de lectura y actualización del usuario de servicio, el código exacto del idioma, la selección de recursos para sincronizar, el modo y la configuración del entorno del webhook. Resuelve cualquier problema de acceso a la instancia o de rechazo de la clave antes de solicitar una nueva traducción.
Cambia la configuración o desconecta #
Cambia la selección de recursos, los idiomas, el motor de localización y el modo en Studio. Cambia el nombre de la conexión o gestiona sus credenciales en Configuración → Integraciones. Estos cambios conservan su URL de webhook.
Para renovar la clave de API, abre la conexión en Configuración → Integraciones y selecciona Sustituir clave. Introduce una clave de la misma colección de autenticación y vuelve a introducir todas las cabeceras personalizadas que la instancia siga necesitando; las cabeceras que facilites sustituirán a las guardadas.
Para cambiar la dirección de la instancia, necesitas una nueva conexión. Configura su ámbito de traducción y actualiza el entorno de Payload con la nueva URL de webhook antes de volver a depender de las notificaciones automáticas.
Al desconectar, se eliminan el historial local y el estado de sincronización de la conexión y se detienen las futuras lecturas y escrituras. El contenido ya traducido permanece en Payload. Elimina el antiguo valor de la variable de entorno del webhook o la función que lo activa, y revoca por separado la clave de servicio si ya no la necesitas.
Una nueva conexión establece una nueva referencia de partida. Su primera sincronización conserva las traducciones existentes que cumplan los criterios y completa lo que falte; no restaura el historial local de ejecuciones de una conexión anterior. Revisa esa primera ejecución como harías con cualquier conexión nueva.