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.
La integración de Payload se activa por organización. Si no la ves en Settings -> Integrations, ponte en contacto con nosotros y la activaremos por ti.
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: trueen tu colección de autenticación (normalmenteusers), 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.
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 tu defaultLocale de Payload como idioma de origen, porque es el idioma cuyos cambios vigila el plugin.
Conecta tu instancia de Payload#
Abre la integración
Ve a Settings -> Integrations y haz clic en Connect en Payload CMS.
Introduce los datos de tu instancia
| Campo | Qué debes introducir |
|---|---|
| Nombre de la conexión | Una etiqueta como Production o Staging |
| URL base de Payload | La URL raíz de tu instancia, por ejemplo, https://cms.example.com. Solo HTTPS |
| Slug de la colección de autenticación | La colección a la que pertenece la clave API de tu servicio, normalmente users |
| Clave API | La clave API del usuario de servicio |
| Cabeceras personalizadas | Opcional. Se envía con cada solicitud a tu instancia |
Lingo.dev verifica la clave con tu instancia antes de continuar.
Elige qué traducir
| Ajuste | Qué hace |
|---|---|
| Colecciones y globales | Marca las que quieras traducir. Una fila marcada como No read + update seguirá deshabilitada hasta que el usuario de servicio tenga acceso a ella |
| Idioma de origen | El idioma en el que escriben tus editores. Usa tu defaultLocale de Payload |
| Idiomas de destino | Los idiomas a los que traducir |
| Motor | El motor de localización que traduce este contenido |
| Traducir guardados en borrador | Desactivado: traduce solo los cambios publicados. Activado: también traduce los guardados en borrador y mantiene las traducciones como borradores |
Instala el plugin
El último paso muestra la URL de tu webhook. Cópiala ahora. Solo se muestra una vez. Guárdala como LINGO_WEBHOOK_URL en el entorno de Payload, luego instala el plugin y añádelo 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,
}),
],
});Vuelve a desplegar Payload. A partir de ese momento, cada cambio publicado en el idioma de origen se enviará a Lingo.dev para su traducción.
Qué hace el plugin
Añade un endpoint GET /api/lingo/schema que 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 un global. El alcance, los idiomas y el motor se gestionan en 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 tres pestañas: Collections, Globals y Runs.
El alcance se define por colección y por global. Todos los documentos de una colección seleccionada quedan incluidos. Para cambiar el alcance, los idiomas, el motor o el ajuste de borrador, haz clic en Edit configuration en la cabecera de la página. Los cambios se aplican en la siguiente ejecución sin necesidad de volver a desplegar.
Dentro de un documento, la configuración de campos de Payload decide qué se traduce:
| Campo | Traducido |
|---|---|
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 integrados 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 ningún campo padre localizado | No |
id, blockType, blockName | No |
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 guardes un documento o un global en el idioma de origen, se notificará a Lingo.dev. Los guardados que se hagan en un intervalo breve de tiempo se agrupan en una única ejecución. Se ignoran los guardados en otros idiomas, los guardados de borradores (salvo que esté activada la opción Traducir guardados de borradores) y el contenido que quede fuera de tu ámbito.
Ejecuciones manuales. Cada fila de colección, global y documento tiene dos botones:
| Botón | Qué hace | Cuándo usarlo |
|---|---|---|
| Sync | Traduce solo lo que ha cambiado desde la última ejecución | Para completar contenido después de conectar o volver a intentarlo tras un fallo |
| Retranslate | Vuelve a traducirlo todo en la fila desde cero | Después de cambiar el glosario, la voz de marca o las reglas de tu motor |
Abre una colección para acceder a sus documentos y sincronizarlos uno a uno. Ambas pestañas muestran cuándo se sincronizó cada elemento por última vez.
No se traduce nada al conectar. Para traducir lo que ya tienes, haz clic en Sync en cada colección y global. Si añades un idioma de destino más adelante, funciona igual: el siguiente Sync lo rellenará.
Solo puede haber una ejecución en curso por conexión. Las solicitudes posteriores se ponen en cola y arrancan por orden. Mientras una fila esté cubierta por una ejecución en cola o en curso, sus botones mostrarán Syncing....
Retranslate sobrescribe las ediciones manuales
Retranslate regenera todos los campos traducidos dentro de su alcance, incluidas las traducciones que tu equipo haya editado manualmente en Payload. Sync solo regenera los campos cuyo texto de origen ha cambiado, así que las ediciones manuales en el resto se conservan.
Supervisar una ejecución#
La pestaña Runs muestra cada ejecución con su estado, el desencadenante (Webhook o Manual, sync o retranslate), la hora de inicio y la duración. Desde la lista puedes cancelar cualquier ejecución en cola o en curso.
Abre una ejecución para ver en qué fase está (lectura desde Payload, traducción o escritura de vuelta), el progreso general, el progreso por cada idioma de destino y los documentos, colecciones y globales que incluye. Cada elemento enlaza al panel de administración de Payload.
| Estado | Significado |
|---|---|
| En cola | Esperando a que termine la ejecución anterior |
| En curso | En progreso |
| Completada | Se han escrito de vuelta todas las traducciones |
| Actualizado | No ha cambiado nada dentro del alcance desde la última ejecución. No es un fallo |
| Fallida | La ejecución se detuvo. El motivo se muestra en la parte superior del detalle de la ejecución |
| Cancelada | Detenida por alguien de tu equipo |
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#
Con Translate draft saves desactivado, que es la opción predeterminada, 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 cambio de borrador sin publicar que contenga pasa a publicarse junto con la traducción.
Con esta opción activada, los guardados en borrador también inician ejecuciones. Lingo.dev lee el borrador más reciente del contenido de origen y escribe 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.
Gestionar la conexión#
Rotar la URL del webhook#
Abre el menú en la cabecera de la página de conexión y elige Regenerar URL del webhook. La URL anterior deja de funcionar de inmediato. Actualiza LINGO_WEBHOOK_URL y vuelve a desplegar. Si editas la conexión, la URL se mantiene.
Desconectar#
Desconecta desde Settings -> Integrations -> Payload CMS. 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 quita el plugin de tu configuración.
Volver a conectar implica una nueva URL de webhook
Una conexión nueva recibe una nueva URL de webhook, 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 todos los documentos dentro del alcance, conserva las traducciones que Payload ya tenga y rellena los huecos que falten.
Límites#
| Límite | Detalle |
|---|---|
| Versión de Payload | Payload 3 con la 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 |
| URL base | Solo HTTPS |
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 un global muestra "No read + update". Concede al usuario de servicio permisos de lectura y actualización en la configuración de acceso de esa colección y vuelve a abrir la configuración.
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.
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 conexión muestra "Couldn't reach this Payload instance". Comprueba que la instancia esté disponible, que la clave siga siendo válida y que las cabeceras de la pasarela sigan funcionando. Actualiza la conexión en Settings -> Integrations.
