Plugin para o Payload CMS

Disponibilize o esquema de localização do Payload e notifique o Lingo.dev quando o conteúdo de origem mudar, sem alterar a forma como o editor guarda o conteúdo.

O Lingo.dev precisa de saber quais os campos do Payload que contêm texto localizável e quando o respetivo conteúdo de origem muda. O @lingo.dev/payloadcms assegura essas duas ligações: um endpoint de acesso autenticado ao esquema e notificações opcionais de alterações na origem. A seleção do conteúdo a traduzir e a gravação das traduções são configuradas através da integração com o Payload.

Registar o plugin #

Numa aplicação Payload 3 existente, instale:

sh
npm install @lingo.dev/payloadcms@0.1.5

Adicione lingo à lista de plugins existente da aplicação e mantenha a respetiva configuração de localização:

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

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

Este exemplo mostra os campos relevantes, não uma configuração completa e autónoma do CMS. Mantenha as coleções, os globais, o adaptador de base de dados, o editor e as restantes definições obrigatórias já existentes.

O pacote exporta lingo e LingoPluginOptions. A função lingo() devolve um plugin do Payload e a sua única opção é webhookUrl?: string. Registar o plugin sem esse URL também disponibiliza o endpoint do esquema, permitindo configurar a descoberta do esquema antes das notificações automáticas.

Inspecionar o esquema com a autenticação do Payload #

O plugin acrescenta GET /lingo/schema ao caminho base da API do Payload, normalmente /api/lingo/schema, mantendo os endpoints existentes. Faça um pedido para uma coleção ou um global conhecido:

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

Utilize os slugs da sua aplicação. O processador exige um utilizador autenticado no Payload; um pedido não autenticado devolve 401 e uma entidade em falta ou desconhecida devolve 404. A integração utiliza a autoridade do Payload configurada para ler este endpoint.

A resposta apresenta os nomes dos campos, os tipos, os indicadores de localização, a estrutura aninhada e os valores predefinidos relevantes já resolvidos. Inclui as estruturas aninhadas suportadas — grupos, matrizes, blocos, separadores e esquemas de blocos Lexical — necessárias para localizar o texto. Omite as configurações de administração e do editor que não são relevantes, em vez de serializar toda a configuração do Payload.

Os valores predefinidos são resolvidos para os campos de texto abrangidos que são apresentados a quem cria conteúdo. Os valores predefinidos restritos ou ocultos, os campos estruturais e os valores que não podem ser resolvidos ou serializados são excluídos dos valores predefinidos devolvidos. O esquema descreve o que a integração pode examinar; obtê-lo não constitui um pedido de tradução.

Notificar a integração após uma alteração na origem #

Depois de ligar o Payload no Lingo.dev, guarde o URL de capacidade emitido na configuração do servidor e passe-o ao 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 });

Utilize plugin na matriz plugins existente, em vez de lingo(). O nome da variável de ambiente fica ao critério de quem configura a aplicação. O próprio URL autoriza as notificações; não o inclua em pacotes de código para o navegador, em código-fonte registado em commits nem em registos.

Com o URL e localization.defaultLocale configurados, o plugin acrescenta hooks afterChange às coleções e aos globais, preservando os hooks existentes. Uma notificação de coleção envia o respetivo slug, o ID do documento e, opcionalmente, o estado do documento. Uma notificação de global envia o respetivo slug. Os dados enviados são uma referência, não o documento completo: a integração volta a ler o conteúdo com as credenciais configuradas.

As alterações efetuadas explicitamente noutro idioma são ignoradas, evitando que a gravação das traduções no idioma de destino inicie repetidamente a tradução do conteúdo de origem. Uma alteração sem indicação explícita do idioma pode desencadear uma notificação. O pedido tem um tempo limite de cinco segundos e as falhas de transporte são ignoradas para permitir que o editor conclua a gravação. O hook também não impede a gravação quando recebe um código de estado HTTP de insucesso.

Confirmar o resultado da ligação #

Primeiro, verifique se a integração consegue ler o esquema pretendido com as respetivas credenciais do Payload. Em seguida, efetue uma alteração autorizada na origem através do workflow de integração e verifique o resultado no idioma de destino. Se o conteúdo de origem for guardado, mas não surgir conteúdo de destino, verifique a aceitação da notificação e a execução da tradução, em vez de presumir que guardar no editor comprova a entrega.

Escolha as coleções, os idiomas de destino e o motor de localização na configuração da integração do Lingo.dev. Estas definições não são opções do plugin, pelo que podem ser alteradas sem substituir este registo na aplicação.