Plugin de Payload CMS

Expón el esquema de localización de Payload y notifica a Lingo.dev cuando cambie el contenido de origen, sin alterar la forma en que el editor guarda los cambios.

Lingo.dev necesita saber qué campos de Payload contienen texto localizable y cuándo cambia su contenido de origen. @lingo.dev/payloadcms ofrece esas dos conexiones: un endpoint de esquema autenticado y notificaciones opcionales de cambios en el contenido de origen. La selección del contenido que se traducirá y la escritura de las traducciones se configuran mediante la integración con Payload.

Registra el plugin #

En una aplicación existente de Payload 3, instala:

sh
npm install @lingo.dev/payloadcms@0.1.5

Agrega lingo a la lista de plugins existente de la aplicación y conserva su configuración de localización:

ts
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";

export default buildConfig({
  localization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  plugins: [lingo()],
});

Este ejemplo muestra los campos relevantes, no una configuración completa e independiente del CMS. Conserva las colecciones, los globales, el adaptador de base de datos, el editor y los demás ajustes necesarios que ya tengas.

El paquete exporta lingo y LingoPluginOptions. lingo() devuelve un plugin de Payload y su única opción es webhookUrl?: string. Registrarlo sin esa URL también expone el endpoint de esquema, así que puedes configurar la detección del esquema antes de habilitar las notificaciones automáticas.

Inspecciona el esquema mediante la autenticación de Payload #

El plugin agrega GET /lingo/schema a la ruta base de la API de Payload, que normalmente es /api/lingo/schema, y conserva los endpoints existentes. Solicita una colección o un global conocido:

text
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage

Usa los slugs de tu aplicación. El controlador requiere un usuario autenticado de Payload; una solicitud sin autenticar devuelve 401, y una entidad ausente o desconocida devuelve 404. La integración usa la autorización de Payload que tiene configurada para leer este endpoint.

La respuesta muestra los nombres y tipos de campos, los indicadores de localización, la estructura anidada y los valores predeterminados resueltos que sean relevantes. Incluye las estructuras anidadas compatibles —grupos, arreglos, bloques, pestañas y esquemas de bloques de Lexical— necesarias para ubicar el texto. Omite la configuración de administración y del editor que no sea pertinente, en lugar de serializar toda la configuración de Payload.

Los valores predeterminados se resuelven para los campos de texto que participan y están destinados a quienes crean contenido. Los valores predeterminados restringidos u ocultos, los campos estructurales y los valores que no se pueden resolver o serializar se excluyen de la salida de valores predeterminados. El esquema describe lo que la integración puede examinar; obtenerlo no solicita una traducción.

Notifica a la integración después de un cambio en el contenido de origen #

Después de conectar Payload en Lingo.dev, guarda la URL de autorización emitida en la configuración del servidor y pásala al plugin:

ts
const webhookUrl = process.env.LINGO_PAYLOAD_WEBHOOK_URL;
if (!webhookUrl) throw new Error("Set LINGO_PAYLOAD_WEBHOOK_URL for automatic notifications");

const plugin = lingo({ webhookUrl });

Usa plugin en el arreglo plugins existente en lugar de lingo(). Tú eliges el nombre de la variable de entorno para tu aplicación. La URL por sí sola autoriza las notificaciones; mantenla fuera de los paquetes del navegador, del código fuente guardado en el repositorio y de los registros.

Con la URL y localization.defaultLocale configurados, el plugin agrega hooks afterChange a las colecciones y los globales, sin alterar los hooks existentes. Una notificación de colección envía su slug, el ID del documento y, opcionalmente, el estado del documento. Una notificación de global envía su slug. Los datos enviados son una referencia, no el documento completo: la integración vuelve a leer el contenido con las credenciales que tiene configuradas.

Se omiten los cambios realizados explícitamente en otro idioma, lo que evita que la escritura de las traducciones en el idioma de destino active una y otra vez la traducción del contenido de origen. Un cambio sin un idioma explícito puede activar una notificación. La solicitud tiene un tiempo de espera de cinco segundos y los errores de transporte se ignoran para que el editor pueda completar el guardado. El hook tampoco hace que el guardado falle si se recibe un código de estado HTTP que indica un error.

Confirma el resultado de la conexión #

Primero, verifica que la integración pueda leer el esquema esperado con sus credenciales de Payload. Luego, realiza un cambio autorizado en el contenido de origen mediante el flujo de trabajo de la integración y revisa el contenido resultante en el idioma de destino. Si el contenido de origen se guarda pero no llega ninguna traducción, comprueba si se aceptó la notificación y revisa la ejecución de la traducción, en lugar de asumir que el guardado en el editor confirma la entrega.

Elige las colecciones, los idiomas de destino y el motor de localización en la configuración de la integración de Lingo.dev. Estos ajustes no son opciones del plugin, así que puedes cambiarlos sin reemplazar el registro del plugin en la aplicación.