Payload CMS
Traduce los campos localizados de Payload 3, conserva la estructura de los recursos y elige cómo llegan los cambios del contenido de origen a los idiomas de destino.
Payload ya tiene un espacio para las versiones en distintos idiomas de cada campo localizado. 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 globales y la publicación siguen 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 existentes siguen funcionando.
Empieza con un recurso y una sincronización manual. Después de revisar el resultado, agrega notificaciones de cambios en el contenido de origen si quieres que la traducción se actualice automáticamente con cada edición.
La integración con Payload CMS está disponible con el plan Enterprise. Consulta los precios para conocer la disponibilidad actual. Configuración → Integraciones muestra No disponible en tu plan junto a Payload cuando la organización necesita un plan que le dé acceso.
Prepara Payload y un usuario de servicio #
Usa Payload 3 con la localización configurada. La traducción de texto enriquecido es compatible con el editor Lexical, pero no con el editor anterior, 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. Dale acceso de lectura y actualización a todas las colecciones o globales que quieras traducir. Las escrituras se atribuyen a este usuario. Si una puerta de enlace requiere encabezados adicionales, agrégalos al conectar y mantén sus valores en secreto.
Haz coincidir el idioma de origen de la conexión con localization.defaultLocale de Payload, que es el idioma en el que el complemento detecta cambios. Los códigos de origen y destino deben coincidir exactamente con los configurados en Payload: en y en-US identifican idiomas diferentes. Elige un motor de localización al que tengas acceso en la organización de Lingo.dev conectada. Si no puedes agregar la conexión, revisa los permisos de tu organización y su derecho de conexión.
Conecta la instancia y expón su esquema #
Abre Configuración → Integraciones y selecciona Conectar para Payload CMS. Ingresa 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 servicio y los encabezados de la puerta de enlace, si los hay. Selecciona Conectar para verificar el acceso y guardar la conexión. Conserva la URL del webhook que aparece después para las notificaciones automáticas.
Instala el complemento en el proyecto de Payload:
pnpm add @lingo.dev/payloadcmsAgrega lingo al arreglo plugins existente. Este fragmento muestra la configuración del complemento; conserva las colecciones, los 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 usa este punto de acceso para identificar los campos localizados. Puedes crear una conexión antes de instalar el complemento, pero la traducción requiere el punto de acceso del esquema.
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: tener la URL permite 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 luego selecciona Configurar. Elige su motor de localización, los idiomas de origen y destino y el modo de escritura de resultados. Selecciona Continuar y luego elige las colecciones y los globales que quieras traducir. Los modos de publicación se describen a continuación.
Traduce un recurso #
Elige una colección o un global que contenga un campo de texto localizado breve, y un idioma de destino. Anota los 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 contenido publicado. |
Payload mantiene un solo borrador compartido por documento y lo publica completo. Por eso, guardar una traducción en un documento publicado que tiene cambios sin publicar también publicaría esos cambios. En estos casos, el modo Publicar deja el documento sin cambios y marca la traducción como fallida. Publica los cambios o vuelve a la versión publicada en Payload y luego ejecuta Sincronizar de nuevo. Para ver esos cambios, el usuario asociado a la clave de API necesita acceso de 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 verificación: el modo Publicar guarda la traducción en él y el documento sigue siendo un borrador. La verificación se realiza justo antes de cada escritura, por lo que un borrador guardado mientras tanto aún podría publicarse junto con la traducción. Evita guardar borradores de documentos mientras una sincronización escribe en ellos y revisa su estado de publicación después. El comportamiento de los borradores también depende de tu configuración de Payload; verifica la versión que está publicada cuando pruebes una actualización.
Ejecuta Sincronizar, abre la ejecución del flujo de trabajo correspondiente y revisa el campo de destino directamente en Payload. Comprueba la redacción, los enlaces, la estructura del texto enriquecido, el idioma y el estado de publicación. Luego revisa el contenido en el sitio que lo utiliza. La conexión por sí sola no traduce el catálogo.
La primera sincronización conserva las traducciones existentes que están completas, sin reemplazarlas. Completa los campos faltantes, incluidos aquellos cuyo valor actual solo repite el valor predeterminado de Payload. Si se conservó un campo, compara su valor con ese estado antes de solicitar un reemplazo.
Selecciona recursos y campos #
Las tablas Colecciones y Globales tienen interruptores de Sincronizar cuyo estado se conserva. Seleccionar una colección abarca todos sus documentos; seleccionar un global abarca ese recurso. Las acciones del encabezado procesan los recursos habilitados. Cuando hay acciones para las filas seleccionadas, estas ponen en cola el conjunto 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 dentro de grupos, arreglos, 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, números, relaciones, archivos cargados, código y JSON arbitrario no se vuelven traducibles solo porque selecciones 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 oraciones a través del formato en línea y los enlaces, y luego reconstruye el árbol con sus enlaces, medios y bloques. Prueba un documento representativo antes de ampliar el alcance, especialmente si tu proyecto usa 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 después de 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 almacenadas, aplica el alcance 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 que se guarden las ediciones, así que un guardado exitoso por sí solo no confirma la entrega. Si no se procesó un cambio, revisa el historial de ejecuciones y usa la sincronización manual para conciliar el contenido. Los guardados de borradores cuentan en el modo Borrador; un guardado en el idioma de destino o un recurso fuera del alcance no cuentan como un cambio de origen para esta conexión.
Usa Sincronizar para procesar cambios en el contenido de origen y completar el contenido de destino faltante. Esta acción compara el contenido con la referencia disponible. Si un artefacto de origen anterior no está disponible, la recuperación puede regenerar el contenido afectado. Por eso, revisa las diferencias en lugar de suponer que se conservarán todas las ediciones manuales. Después de agregar un idioma de destino, ejecuta la sincronización para completarlo.
Usa Volver a traducir cuando quieras reemplazar las traducciones seleccionadas, incluidos los campos editados manualmente. Por ejemplo, un cambio importante en las instrucciones del motor de localización puede justificar nuevos resultados aunque el contenido de origen no haya cambiado. Las solicitudes quedan en cola despué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 con escrituras parciales #
El paso de escritura de resultados vuelve a leer el contenido de origen. Si alguien lo editó después de la planificación, se omite el documento en lugar de aplicar los valores traducidos a una revisión distinta o a un arreglo con otro orden. Una sincronización posterior concilia el nuevo contenido de origen.
Las ejecuciones fallidas o canceladas conservan las escrituras exitosas. En Ejecuciones de flujo de trabajo, distingue las tareas completadas, al día, omitidas, fallidas y canceladas, y revisa los recursos afectados antes de volver a intentarlo. Detener cancela el trabajo activo cuando la opción está disponible; no revierte los campos ya escritos. Un resultado al día significa que no había ningún cambio seleccionado para procesar.
Si los resultados no aparecen, revisa el punto de acceso del esquema, la localización y el tipo de 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 el entorno del webhook. Resuelve cualquier problema de acceso a la instancia o 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 administra sus credenciales en Configuración → Integraciones. Estos cambios conservan la URL del webhook.
Para rotar la clave de API, abre la conexión en Configuración → Integraciones y selecciona Reemplazar clave. Ingresa una clave de la misma colección de autenticación y vuelve a ingresar todos los encabezados personalizados que la instancia aún necesite; los encabezados que proporciones reemplazan los almacenados.
Cambiar la dirección de la instancia requiere una conexión nueva. Configura su alcance de traducción y actualiza el entorno de Payload con la nueva URL del 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 lecturas y escrituras futuras. El contenido ya traducido permanece en Payload. Elimina el valor de entorno o la función de enlace del webhook anterior y revoca la clave de servicio por separado si ya no la necesitas.
Una conexión nueva establece una nueva referencia. Su primera sincronización conserva las traducciones existentes que cumplen los criterios y completa los campos faltantes; no restaura el historial local de ejecuciones de una conexión anterior. Revisa esa primera ejecución como lo harías con cualquier conexión nueva.