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 en cada idioma.
Funciona con proyectos de Payload 3 que tienen la localización habilitada 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 en el documento se deja tal cual.
Payload CMS está disponible con el plan Enterprise. Si la página Conectar muestra Payload CMS no está en tu plan, contáctanos y lo resolvemos.
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 definidos en tu configuración de Payload.
- Un usuario de servicio con una API key. Configura
useAPIKey: trueen tu colección de autenticación (normalmenteusers), crea un usuario para Lingo.dev y genera una API key para ese usuario en el panel de administración de Payload. Ese usuario necesita acceso de lectura y actualización a cada colección y global que quieras traducir. - Un motor de localización. Su glosario, voz de marca y reglas definen cómo se hacen las traducciones.
Los códigos de idioma deben coincidir con tu configuración de Payload
Los idiomas que elijas en Lingo.dev deben coincidir exactamente con los códigos de localization.locales. Si Payload tiene en y de, elige English y German, no English (United States): en-US y en son idiomas distintos. Usa el defaultLocale de tu Payload como idioma de origen, porque ese es el idioma cuyos cambios monitorea el plugin.
Conecta tu instancia de Payload#
Abre la integración
Ve a Studio -> All integrations y haz clic en Conectar en la tarjeta de Payload CMS.
Ingresa los datos de tu instancia
| Campo | Qué ingresar |
|---|---|
| Dirección | La URL raíz de tu instancia, por ejemplo https://cms.example.com. Solo HTTPS |
| Colección de autenticación | La colección a la que pertenece tu API Key de servicio, normalmente users |
| Clave de API | La API key del usuario de servicio |
| Encabezados personalizados | Opcional. Se envía en cada solicitud a tu instancia. Haz clic en Add header para cada uno o pega una línea Name: value para completar una fila |
Haz clic en Verify instance. Lingo.dev verifica la clave con tu instancia antes de continuar.
Elige qué traducir
| Configuración | Qué hace |
|---|---|
| Nombre | Cómo quieres llamar esta conexión, por ejemplo Production o Staging, para distinguir tus instancias |
| Colecciones y globales | Haz clic en las que quieras traducir. El usuario de servicio que no puede leer ni actualizar aparece tachado y no se puede seleccionar hasta que tenga acceso |
| Motor | El motor de localización cuyo glosario, reglas y voz de marca siguen estas traducciones |
| Idioma de origen | El idioma en el que escribe tu equipo editorial. Usa tu defaultLocale de Payload |
| Idiomas de destino | Los idiomas a los que se traducirá |
| Modo | Publish traduce solo los cambios publicados y publica las traducciones. Draft también traduce los guardados como borrador y guarda las traducciones como borradores. Consulta Borradores vs. Publicado más abajo |
Haz clic en Conectar.
Instala el plugin
El último paso muestra tu Webhook URL. Cópiala ahora. Solo se muestra una vez. Guárdala como LINGO_WEBHOOK_URL en tu entorno de Payload y luego instala el plugin y agrégalo a tu configuración:
pnpm add @lingo.dev/payloadcmsimport { 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,
}),
],
});Haz clic en Done y luego vuelve a desplegar Payload. A partir de ahora, cada cambio publicado en el idioma de origen se enviará a Lingo.dev para su traducción.
Qué hace el plugin
Agrega un endpoint GET /api/lingo/schema que le indica a Lingo.dev cuáles de tus campos son texto localizado, y un hook que avisa a Lingo.dev cuando cambia un documento o global. El alcance, los idiomas y el motor se administran desde el panel, así que puedes cambiarlos sin volver a desplegar. Omite webhookUrl para no usar el hook e iniciar cada traducción desde el panel.
Elige qué se traduce#
La página de conexión tiene cuatro pestañas: Collections, Globals, Ejecuciones de flujo de trabajo y Configuración.
El alcance se configura por colección y por global. Las pestañas Collections y Globals muestran todo lo que ofrece tu instancia, una fila por elemento, incluida la última vez que se sincronizó. Cada fila tiene un interruptor de Sync: actívalo y, a partir de ese momento, se incluirán todos los documentos de esa colección o de ese global. El cambio se guarda en cuanto lo activas y se aplica a la siguiente ejecución sin necesidad de volver a desplegar. El interruptor en el encabezado de la tabla activa o desactiva Sync para todo lo que aparece en la lista.
Una fila marcada como no read + update está bloqueada: el usuario de 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 Configuración.
Dentro de un documento, la configuración de campos de Payload define qué se traduce:
| Campo | Se traduce |
|---|---|
Campos text, textarea y richText marcados como localized: true | Sí |
Los mismos tipos de campo dentro de un group, array, blocks o tabs localizado | Sí |
| Bloques y bloques en línea incrustados en texto enriquecido | Sí, sus campos de texto siguen las mismas reglas |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | No |
| Campos que no están localizados y no tienen un elemento padre localizado | No |
id, blockType, blockName | No |
El texto enriquecido se traduce como un árbol de Lexical. Se conservan el formato, los enlaces, las cargas y la estructura de bloques, y solo se reemplaza el texto interno. Una oración dividida por texto en negritas o por un enlace se traduce como una sola oración.
Para incluir un campo en el alcance, márcalo como localized: true en Payload y vuelve a desplegar. La siguiente ejecución lo detectará.
Sincroniza y vuelve 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 realizados dentro de una ventana breve se agrupan en una sola ejecución. Los guardados en otros idiomas, los guardados como borrador (a menos que la conexión esté en modo Draft) y el contenido fuera de tu alcance se ignoran.
Ejecuciones manuales. Dos botones, dos tareas distintas:
| Botón | Qué hace | Cuándo usarlo |
|---|---|---|
| Sync | Traduce solo lo que cambió desde la última ejecución | Para completar contenido después de conectar o reintentar tras una falla |
| Retranslate | Vuelve a traducir todo lo que está dentro del alcance, desde cero | Después de cambiar el glosario, la voz de marca o las reglas de tu motor |
Ambos están en el encabezado de la página y abarcan todo lo que tenga Sync activado. Retranslate desde el encabezado primero te pide confirmación. Para ejecutar solo algunas colecciones o globals, marca sus filas: aparecerán Queue sync (N) y Queue retranslation (N) y abarcarán solo esas filas. Una fila solo se puede marcar una vez que su interruptor de Sync esté activado.
Al conectar, no se traduce nada. Para traducir lo que ya tienes, haz clic en Sync en el encabezado de la página. Agregar un idioma de destino más adelante funciona igual: el siguiente Sync lo completará.
Solo puede haber una ejecución en curso por conexión. Las solicitudes adicionales se ponen en cola y comienzan en orden.
Retranslate sobrescribe las ediciones manuales
Retranslate vuelve a generar cada campo traducido dentro de su alcance, incluidas las traducciones que tu equipo haya editado manualmente en Payload. Sync solo vuelve a generar los campos cuyo texto de origen cambió, así que las ediciones manuales en otros campos se conservan.
Sigue una ejecución#
La pestaña Ejecuciones de flujo de trabajo muestra cada ejecución: cuándo comenzó, qué la activó (Webhook o Manual, y luego Sync o Retranslate), qué idiomas abarcó, cuánto tardó y su estado. Una ejecución en cola o en curso tiene un botón Stop. Abre una fila para ver el resultado por idioma.
| Estado | Significado |
|---|---|
| En cola | En espera de la ejecución que va antes |
| En curso | En progreso |
| Completada | Se escribió de vuelta cada traducción |
| Up to date | Nada dentro del alcance cambió desde la última ejecución. No es una falla |
| Fallida | La ejecución se detuvo. El motivo se muestra en la fila de la ejecución |
| Cancelada | La detuvo alguien de tu equipo |
Si una ejecución falla, conserva lo que ya escribió. El mensaje de error indica qué documentos no se escribieron, y la siguiente Sync vuelve a intentarlo. Si una persona editora guarda un documento a mitad de la ejecución, se omite y se retoma en la siguiente.
Dónde terminan las traducciones#
Cada traducción se escribe en el mismo documento o global, en su idioma de destino, siguiendo el propio modelo de localización de Payload. Solo se escriben los campos traducidos. Todos los demás campos permanecen intactos. 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 tenga un idioma de destino se mantiene y solo se traducen los campos faltantes. Un campo que todavía conserva su valor predeterminado de Payload cuenta como faltante. Usa Retranslate para reemplazar traducciones existentes.
Borradores vs. publicado#
En el 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 en ese documento pasa a estar visible junto con la traducción.
En el modo Draft, los guardados como borrador también inician ejecuciones. Lingo.dev lee el borrador más reciente del origen 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 Configuración.
Administrar la conexión#
Configuración#
La pestaña Configuración muestra la instancia que lee la conexión, qué colecciones y globals 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 conserva la webhook URL, así que no hace falta volver a desplegar.
La dirección y la clave de API se establecen cuando se crea la conexión y no se pueden cambiar después. Para apuntar Lingo.dev a una dirección o clave distinta, desconecta y vuelve a conectar.
Desconectar#
Disconnect en la parte inferior de la pestaña Configuración hace que Lingo.dev deje de leer y escribir en la instancia. Esto elimina la conexión, su historial de ejecuciones y el registro de lo que se ha traducido. Las traducciones ya escritas permanecen en Payload. Después, elimina LINGO_WEBHOOK_URL o el plugin de tu configuración.
Reconectar significa una nueva URL del webhook
Una conexión nueva obtiene una URL de webhook nueva, así que actualiza LINGO_WEBHOOK_URL y vuelve a desplegar antes de que las ejecuciones automáticas vuelvan a funcionar. La primera sincronización vuelve a leer cada documento dentro del alcance, conserva las traducciones que Payload ya tiene y completa lo que falta.
Límites#
| Límite | Detalle |
|---|---|
| Versión de Payload | Payload 3 con localización configurada |
| Tipos de campo | Campos text, textarea y richText (solo Lexical) marcados como localized |
| Alcance | Colecciones y globales completos. Sin selección por campo |
| Conexiones | Varios por organización, uno por instancia de Payload |
| Ejecuciones simultáneas | Uno por conexión |
| Dirección | Solo HTTPS |
Solución de problemas#
La conexión falla con "Payload rejected the API key". Verifica la key, el slug de la colección de autenticación y que useAPIKey esté habilitado en esa colección.
Una colección o global muestra "no read + update". Otórgale al usuario de servicio acceso de lectura y actualización en la configuración de acceso de esa colección y luego 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". Agrega @lingo.dev/payloadcms a plugins en la configuración de Payload y vuelve a desplegar. Conectar funciona sin el plugin; sincronizar no.
Publicar en Payload no inicia una ejecución. Verifica que LINGO_WEBHOOK_URL esté configurado, que localization esté configurado, que la colección o global esté dentro del alcance, que el guardado se haya hecho en el idioma de origen y que haya sido una publicación y no un borrador, a menos que la conexión esté en modo Draft.
Un campo no se traduce. No tiene localized: true ni en el propio campo ni en un elemento padre, o no es un campo text, textarea o richText.
La pestaña Configuración muestra la conexión como Cannot be reached. Verifica que la instancia esté activa, que la clave siga siendo válida y que cualquier header del gateway siga funcionando. La dirección y la clave no se pueden editar en una conexión existente, así que si alguna cambió, desconecta, vuelve a conectar y actualiza LINGO_WEBHOOK_URL con la nueva webhook URL.