Plugin do Payload CMS

Exponha o esquema de localização do Payload e notifique o Lingo.dev quando o conteúdo de origem mudar, sem alterar o comportamento de salvamento do editor.

O Lingo.dev precisa saber quais campos do Payload contêm texto localizável e quando o conteúdo de origem muda. @lingo.dev/payloadcms oferece essas duas conexões: um endpoint de esquema autenticado e notificações opcionais de alterações na origem. A seleção do conteúdo para tradução e a gravação das traduções são configuradas pela integração com o Payload.

Registre o plugin #

Em uma aplicação existente com Payload 3, instale:

sh
npm install @lingo.dev/payloadcms@0.1.5

Adicione lingo à lista de plugins existente da aplicação e mantenha a 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 apenas os campos relevantes, não uma configuração completa e autônoma do CMS. Mantenha as coleções, os globais, o adaptador de banco de dados, o editor e as demais configurações obrigatórias já existentes.

O pacote exporta lingo e LingoPluginOptions. lingo() retorna um plugin do Payload, e sua única opção é webhookUrl?: string. Mesmo sem essa URL, o registro do plugin expõe o endpoint de esquema. Assim, você pode configurar a descoberta do esquema antes das notificações automáticas.

Inspecione 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, preservando os endpoints existentes. Faça uma requisição para uma coleção ou um global conhecido:

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

Use os slugs da sua aplicação. O manipulador exige um usuário autenticado do Payload: requisições não autenticadas retornam 401, e entidades ausentes ou desconhecidas retornam 404. A integração usa as credenciais de acesso ao Payload configuradas nela para ler esse endpoint.

A resposta apresenta os nomes e tipos dos campos, os indicadores de localização, a estrutura aninhada e os valores padrão resolvidos relevantes. Ela inclui os esquemas compatíveis de grupos aninhados, arrays, blocos, abas e blocos do Lexical necessários para localizar o texto. As configurações administrativas e do editor sem relação com essa finalidade são omitidas, em vez de serializar toda a configuração do Payload.

Os valores padrão são resolvidos para os campos de texto voltados aos autores que participam do processo. Valores padrão restritos ou ocultos, campos estruturais e valores que não podem ser resolvidos ou serializados ficam de fora dessa saída de valores padrão. O esquema descreve o que a integração pode examinar; consultá-lo não solicita uma tradução.

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

Após conectar o Payload no Lingo.dev, armazene a URL de autorização fornecida na configuração do servidor e passe-a 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 });

Use plugin no array plugins existente, no lugar de lingo(). A aplicação define o nome da variável de ambiente. A própria URL autoriza as notificações; não a inclua em pacotes enviados ao navegador, código-fonte versionado ou logs.

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

Alterações feitas explicitamente em outro idioma são ignoradas. Isso impede que a gravação das traduções no idioma de destino reinicie repetidamente a tradução da origem. Uma alteração sem idioma explícito pode disparar uma notificação. A requisição tem um tempo limite de cinco segundos, e as falhas de transporte são ignoradas para permitir que o salvamento no editor seja concluído. O hook também não impede o salvamento ao receber um código de estado HTTP que indique insucesso.

Confirme o resultado da conexão #

Primeiro, verifique se a integração consegue ler o esquema desejado com as credenciais do Payload configuradas nela. Em seguida, faça uma alteração autorizada na origem pelo workflow da integração e confira o resultado no idioma de destino. Se a origem for salva, mas a tradução não chegar, verifique se a notificação foi aceita e confira a execução da tradução, em vez de presumir que o salvamento no editor comprova a entrega.

Escolha as coleções, os idiomas de destino e o engine de localização na configuração da integração do Lingo.dev. Essas configurações não são opções do plugin e podem mudar sem que seja necessário substituir o registro do plugin na aplicação.