Complemento para Payload CMS

Expón el esquema de localización de Payload y avisa a Lingo.dev cuando cambie el contenido de origen, sin alterar el funcionamiento del guardado en el editor.

Lingo.dev necesita saber qué campos de Payload contienen texto localizable y cuándo cambia su contenido de origen. @lingo.dev/payloadcms proporciona ambas conexiones: un punto de acceso al esquema con autenticación y notificaciones opcionales de cambios en el contenido de origen. La selección del contenido que se traduce y la escritura de las traducciones se configuran mediante la integración con Payload.

Registra el complemento #

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

sh
npm install @lingo.dev/payloadcms@0.1.5

Añade lingo a la lista de complementos 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 pertinentes, no una configuración completa y autónoma del CMS. Conserva las colecciones, los elementos 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 complemento de Payload y su única opción es webhookUrl?: string. Aunque lo registres sin esa URL, el punto de acceso al esquema estará disponible, de modo que puedes configurar la detección del esquema antes de configurar las notificaciones automáticas.

Consulta el esquema con la autenticación de Payload #

El complemento añade GET /lingo/schema como ruta relativa a la ruta base de la API de Payload, normalmente /api/lingo/schema, sin modificar los puntos de acceso existentes. Solicita una colección o un elemento 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 utiliza las credenciales de Payload que tiene configuradas para leer este punto de acceso.

La respuesta recoge los nombres y tipos de los campos, los indicadores de localización, la estructura anidada y los valores predeterminados pertinentes ya resueltos. Incluye los grupos anidados, las matrices, los bloques, las pestañas y los esquemas de bloques de Lexical compatibles necesarios para localizar el texto. Omite los ajustes de administración y del editor que no son pertinentes, en lugar de serializar toda la configuración de Payload.

Los valores predeterminados se resuelven para los campos de texto incluidos que utilizan quienes crean contenido. Los valores predeterminados restringidos u ocultos, los campos estructurales y los valores que no se pueden resolver o serializar quedan excluidos de los valores predeterminados devueltos. El esquema describe lo que la integración puede examinar; obtenerlo no supone solicitar una traducción.

Notifica a la integración tras un cambio en el contenido de origen #

Tras conectar Payload en Lingo.dev, guarda la URL de autorización proporcionada en la configuración del servidor y pásala al complemento:

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 la matriz plugins existente en lugar de lingo(). Puedes elegir el nombre de la variable de entorno para tu aplicación. La propia URL autoriza las notificaciones; no la incluyas en los paquetes del navegador, en el código fuente guardado en el repositorio ni en los registros.

Con la URL y localization.defaultLocale configurados, el complemento añade funciones de enlace afterChange a las colecciones y los elementos globales, sin modificar las existentes. Las notificaciones de colección envían su slug, el ID del documento y, opcionalmente, el estado del documento. Las notificaciones de elementos globales envían 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 para evitar que la escritura de traducciones en el idioma de destino vuelva a iniciar repetidamente 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 guardado en el editor pueda completarse. La función de enlace tampoco impide el guardado si la respuesta tiene un código de estado HTTP de error.

Comprueba el resultado de la conexión #

Primero, comprueba que la integración puede leer el esquema previsto con sus credenciales de Payload. Después, realiza un cambio autorizado en el contenido de origen mediante el flujo de trabajo de la integración y revisa el resultado en el idioma de destino. Si el contenido de origen se guarda pero no llega ninguna traducción, comprueba si se ha aceptado la notificación y revisa la ejecución de la traducción, en lugar de dar por hecho 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 complemento, por lo que puedes cambiarlos sin sustituir el registro del complemento en la aplicación.