Payload CMS

Conecta tu Payload CMS a un motor de localización, elige las colecciones y los globales que quieres incluir, y Lingo.dev traduce sus campos localizados a tus idiomas de destino y los vuelve a escribir en Payload dentro de cada idioma.

Funciona con proyectos de Payload 3 que tienen la localización activada y usan el editor de texto enriquecido Lexical. El editor anterior, Slate, no es compatible. Se traducen los campos localizados text, textarea y richText. Todo lo demás del documento se mantiene tal cual.

Payload CMS está disponible con el plan Enterprise. Si en la página Connect aparece Payload CMS is not on your plan, ponte en contacto con nosotros y lo solucionaremos.

Antes de empezar#

Necesitas tres cosas:

• Payload 3 con la localización configurada. Asegúrate de que el idioma de origen y el de destino coincidan con los idiomas de tu configuración de Payload.
• Un usuario de servicio con una clave API. Activa useAPIKey: true en tu colección de autenticación (normalmente users), crea un usuario para Lingo.dev y genera una clave API para él en el panel de administración de Payload. Este usuario necesita permisos de lectura y actualización en cada colección y global que quieras traducir.
• Un motor de localización. Su glosario, voz de marca y reglas marcan cómo serán las traducciones.

Conecta tu instancia de Payload#

pnpm add @lingo.dev/payloadcms

import { 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,
    }),
  ],
});

Elige qué se traduce#

La página de conexión tiene cuatro pestañas: Collections, Globals, Workflow runs y Settings.

El alcance se configura por colección y por global. Las pestañas Collections y Globals muestran todo lo que ofrece tu instancia, con una fila por elemento y la fecha de la última sincronización. Cada fila tiene un interruptor de Sync: actívalo y, a partir de ese momento, todos los documentos de esa colección o de ese global quedarán incluidos. El cambio se guarda en cuanto lo activas y se aplica en la siguiente ejecución sin necesidad de volver a desplegar. El interruptor de la cabecera de la tabla activa o desactiva Sync para todos los elementos de la lista.

Una fila marcada como no read + update está bloqueada: el usuario del servicio no puede leerla ni actualizarla, así que no se puede traducir. Una fila marcada como not localized yet tiene Sync desactivado.

Los idiomas, el motor y el modo se cambian en la pestaña Settings.

Dentro de un documento, la configuración de campos de Payload decide qué se traduce:

El texto enriquecido se traduce como un árbol de Lexical. Se conservan el formato, los enlaces, las subidas de archivos y la estructura de bloques, y solo se sustituye el texto del interior. Una frase dividida por texto en negrita o por un enlace se traduce como una sola frase.

Para incluir un campo dentro del alcance, márcalo como localized: true en Payload y vuelve a desplegar. La siguiente ejecución lo detectará.

Sincronizar y volver a traducir#

Ejecuciones automáticas. Con webhookUrl configurado en el plugin, cada vez que se guarda un documento o global en el idioma de origen, se notifica a Lingo.dev. Los guardados que se hagan en un breve intervalo se agrupan en una sola ejecución. Los guardados en otros idiomas, los guardados como borrador (salvo que la conexión esté en modo Draft) y el contenido fuera de tu alcance se ignoran.

Ejecuciones manuales. Dos botones, dos tareas distintas:

Ambos están en la cabecera de la página y se aplican a todo lo que tenga Sync activado. Retranslate desde la cabecera te pedirá confirmación antes de continuar. Para ejecutar solo algunas colecciones o globales, marca sus filas: aparecerán Queue sync (N) y Queue retranslation (N), y se aplicarán solo a esas filas. Una fila solo se puede marcar cuando su interruptor Sync está activado.

No se traduce nada al conectar. Para traducir lo que ya tienes, haz clic en Sync en la cabecera de la página. Añadir un idioma de destino más adelante funciona igual: la siguiente sincronización lo completará.

Solo puede haber una ejecución en curso por conexión. Las solicitudes adicionales se ponen en cola y se inician por orden.

Supervisar una ejecución#

La pestaña Workflow runs muestra todas las ejecuciones: cuándo empezaron, qué las activó (Webhook o Manual, y después Sync o Retranslate), qué idiomas incluyeron, cuánto tardaron y cuál es su estado. Una ejecución en cola o en curso tiene un botón Stop. Abre una fila para ver el resultado por idioma.

Si una ejecución falla, conserva todo lo que ya haya escrito. El mensaje de error indica qué documentos no se han escrito, y el siguiente Sync vuelve a intentarlo. Si un editor guarda un documento a mitad de la ejecución, se omite y se retoma en la siguiente.

Dónde acaban las traducciones#

Cada traducción se escribe en el mismo documento o global con su idioma de destino, siguiendo el propio modelo de localización de Payload. Solo se escriben los campos traducidos. El resto de campos no se toca. Las escrituras de vuelta se ejecutan como el usuario del servicio y no activan una nueva ejecución.

Las traducciones existentes se conservan. En la primera sincronización de un documento, todo lo que ya exista en un idioma de destino se mantiene en su sitio y solo se traducen los campos que faltan. Un campo que todavía conserve el valor predeterminado de Payload cuenta como ausente. Usa Retranslate para sustituir las traducciones existentes.

Borradores vs. publicado#

En modo Publish, solo los cambios publicados inician una ejecución y las traducciones se publican en cuanto se escriben. Payload publica el documento completo, así que cualquier edición de borrador no publicada que tenga pasará a estar visible junto con la traducción.

En modo Draft, los guardados como borrador también inician ejecuciones. Lingo.dev lee el borrador más reciente del original y guarda cada traducción como borrador. Nada cambia para tus lectores hasta que alguien publique la traducción en Payload. Úsalo mientras evalúas la calidad de la traducción o cuando las traducciones pasan por revisión.

Puedes cambiar el modo más adelante en la pestaña Settings.

Gestionar la conexión#

Settings#

La pestaña Settings muestra la instancia que usa la conexión para leer, qué colecciones y globales tienen Sync activado y si la conexión está Working o Cannot be reached. Te permite cambiar el nombre, el idioma de origen, los idiomas de destino, el motor y el modo. Cada cambio mantiene la Webhook URL, así que no hace falta volver a desplegar.

La dirección y la clave API se configuran al crear la conexión y no pueden cambiarse después. Para que Lingo.dev apunte a otra dirección o a otra clave, desconecta y vuelve a conectar.

Desconectar#

Disconnect, al final de la pestaña Settings, hace que Lingo.dev deje de leer de la instancia y de escribir en ella. Esto elimina la conexión, su historial de ejecuciones y el registro de lo que se ha traducido. Las traducciones ya escritas seguirán en Payload. Después, elimina LINGO_WEBHOOK_URL o el plugin de tu configuración.

Límites#

Solución de problemas#

La conexión falla con "Payload rejected the API key". Comprueba la clave, el slug de la colección de autenticación y que useAPIKey esté activado en esa colección.

Una colección o global muestra "no read + update". Concede al usuario del servicio acceso de lectura y actualización en la configuración de acceso de esa colección y vuelve a cargar la página de conexión. El interruptor Sync de la fila se desbloqueará.

La primera ejecución falla con "The Lingo plugin isn't installed". Añade @lingo.dev/payloadcms al plugins de la configuración de Payload y vuelve a desplegar. Conectar funciona sin el plugin; sincronizar, no.

Publicar en Payload no inicia una ejecución. Comprueba que LINGO_WEBHOOK_URL esté configurado, que localization esté configurado, que la colección o el global estén dentro del alcance, que el guardado se haya hecho en el idioma de origen y que haya sido una publicación, no un borrador, salvo que la conexión esté en modo Draft.

Un campo no se traduce. No tiene localized: true ni en el propio campo ni en ningún campo padre, o no es un campo text, textarea o richText.

La pestaña Settings muestra la conexión como Cannot be reached. Comprueba que la instancia esté activa, que la clave siga siendo válida y que los encabezados de la pasarela sigan funcionando. La dirección y la clave no se pueden editar en una conexión existente, así que, si una de ellas ha cambiado, desconecta, vuelve a conectar y actualiza LINGO_WEBHOOK_URL con la nueva Webhook URL.

Siguientes pasos#