Payload CMS

Conecte seu Payload CMS a um engine de localização, escolha quais collections e globals incluir, e o Lingo.dev traduz os campos localizados para os idiomas de destino e grava tudo de volta no Payload em cada idioma.

Funciona com projetos Payload 3 com localização ativada e que usam o editor de rich text Lexical. O editor Slate, mais antigo, não é compatível. Os campos localizados text, textarea e richText são traduzidos. Todo o restante do documento permanece como está.

O Payload CMS está disponível no plano Enterprise. Se a página Connect mostrar Payload CMS não está no seu plano, fale com a gente que resolvemos isso.

Antes de começar#

Você precisa de três coisas:

• Payload 3 com localização configurada. Verifique se os idiomas de origem e de destino correspondem aos idiomas definidos na configuração do Payload.
• Um usuário de serviço com chave de API. Defina useAPIKey: true na sua collection de autenticação (geralmente users), crie um usuário para o Lingo.dev e gere uma chave de API para ele no admin do Payload. Esse usuário precisa de acesso de leitura e atualização a todas as collections e globals que você quiser traduzir.
• Um engine de localização. O glossário, a voz da marca e as regras dele orientam as traduções.

Conecte sua instância do Payload#

pnpm add @lingo.dev/payloadcms

import { 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,
    }),
  ],
});

Escolha o que será traduzido#

A página de conexão tem quatro abas: Collections, Globals, Workflow runs e Configurações.

O escopo é definido por coleção e por global. As abas Collections e Globals listam tudo o que sua instância oferece, uma linha por item, junto com a data da última sincronização. Cada linha tem um botão Sync: ative-o e, a partir daí, todo documento dessa coleção ou desse global ficará incluído. A alteração é salva no momento em que você ativa o botão e vale para a próxima execução sem precisar de redeploy. O botão no cabeçalho da tabela ativa ou desativa o Sync para tudo na lista.

Uma linha marcada como no read + update está bloqueada: o usuário de serviço não pode ler nem atualizar esse item, então ele não pode ser traduzido. Uma linha marcada como not localized yet está com o Sync desativado.

Idiomas, engine e modo são alterados na aba Configurações.

Dentro de um documento, é a configuração de campos do Payload que determina o que será traduzido:

O rich text é traduzido como uma árvore do Lexical. A formatação, os links, os uploads e a estrutura dos blocos são preservados, e apenas o texto interno é substituído. Uma frase dividida por texto em negrito ou por um link é traduzida como uma frase única.

Para incluir um campo no escopo, marque-o como localized: true no Payload e faça redeploy. Ele será considerado na próxima execução.

Sincronize e retraduza#

Execuções automáticas. Com webhookUrl definido no plugin, cada salvamento de um documento ou global no idioma de origem notifica o Lingo.dev. Salvamentos feitos em um curto intervalo de tempo são agrupados em uma única execução. Salvamentos em outros idiomas, salvamentos de rascunho (a menos que a conexão esteja no modo Draft) e conteúdo fora do seu escopo são ignorados.

Execuções manuais. Dois botões, dois trabalhos diferentes:

Ambos ficam no cabeçalho da página, onde cobrem tudo com Sync ativado. Retranslate no cabeçalho pede confirmação antes. Para executar só algumas coleções ou globals, marque as linhas delas: Queue sync (N) e Queue retranslation (N) aparecem e cobrem apenas essas linhas. Uma linha só pode ser marcada depois que o botão Sync estiver ativado.

Nada é traduzido ao conectar. Para traduzir o que você já tem, clique em Sync no cabeçalho da página. Adicionar um idioma de destino depois funciona da mesma forma: o próximo Sync vai preenchê-lo.

Só uma execução pode ficar em andamento por conexão. As solicitações seguintes entram na Fila e começam em ordem.

Acompanhe uma execução#

A aba Workflow runs lista todas as execuções: quando começaram, o que as acionou (Webhook ou Manual, depois Sync ou Retranslate), quais idiomas cobriram, quanto tempo levaram e o status. Uma execução na fila ou em andamento tem um botão Stop. Abra uma linha para ver o resultado por idioma.

Uma execução com falha mantém tudo o que já foi gravado. A mensagem de erro lista os documentos que não foram gravados, e a próxima Sync tenta gravá-los novamente. Se um editor salvar um documento no meio da execução, ele será ignorado e retomado na próxima execução.

Onde as traduções aparecem#

Cada tradução é gravada no mesmo documento ou global no idioma de destino, seguindo o próprio modelo de localização do Payload. Apenas os campos traduzidos são gravados. Todos os demais campos permanecem inalterados. As gravações de retorno são executadas como o usuário de serviço e não acionam uma nova execução.

As traduções existentes são mantidas. Na primeira sincronização de um documento, tudo o que já existir em um idioma de destino permanece no lugar, e apenas os campos ausentes são traduzidos. Um campo que ainda mantém o valor padrão do Payload conta como ausente. Use Retranslate para substituir traduções existentes.

Rascunhos vs. Publicado#

No modo Publish, apenas alterações publicadas iniciam uma execução, e as traduções são publicadas assim que são gravadas. O Payload publica o documento inteiro, então qualquer edição de rascunho ainda não publicada nele vai ao ar junto com a tradução.

No modo Draft, salvamentos de rascunho também iniciam execuções. O Lingo.dev lê o rascunho mais recente da origem e grava cada tradução como rascunho. Nada muda para seus leitores até que alguém publique a tradução no Payload. Use isso enquanto avalia a qualidade da tradução ou quando as traduções passam por revisão.

Você pode alterar o modo depois na aba Configurações.

Gerenciar a conexão#

Configurações#

A aba Configurações mostra a instância que a conexão lê, quais coleções e globals estão com Sync ativado e se a conexão está Working ou Cannot be reached. Ela permite alterar o nome, o idioma de origem, os idiomas de destino, o engine e o modo. Cada alteração mantém a webhook URL, então não é preciso fazer redeploy.

O endereço e a chave de API são definidos quando a conexão é criada e não podem ser alterados depois. Para fazer o Lingo.dev apontar para outro endereço ou outra chave, desconecte e conecte novamente.

Desconectar#

Disconnect na parte inferior da aba Configurações faz o Lingo.dev parar de ler e gravar na instância. Isso remove a conexão, o histórico de execuções e o registro do que foi traduzido. As traduções já gravadas permanecem no Payload. Depois, remova LINGO_WEBHOOK_URL ou o plugin da sua configuração.

Limites#

Solução de problemas#

A conexão falha com "Payload rejected the API key". Verifique a chave, o slug da collection de autenticação e se useAPIKey está ativado nessa collection.

Uma coleção ou global mostra "no read + update". Dê ao usuário de serviço acesso de leitura e atualização na configuração de acesso dessa coleção e depois recarregue a página de conexão. O botão Sync da linha será desbloqueado.

A primeira execução falha com "The Lingo plugin isn't installed". Adicione @lingo.dev/payloadcms ao plugins da configuração do Payload e faça redeploy. Conectar funciona sem o plugin; sincronizar não.

Publicar no Payload não inicia uma execução. Verifique se LINGO_WEBHOOK_URL está definido, se localization está configurado, se a coleção ou global está dentro do escopo, se o salvamento foi no idioma de origem e se foi uma publicação, e não um rascunho, a menos que a conexão esteja no modo Draft.

Um campo não é traduzido. Ele não tem localized: true nele ou em um campo pai, ou não é um campo text, textarea ou richText.

A aba Configurações mostra a conexão como Cannot be reached. Verifique se a instância está no ar, se a chave ainda é válida e se os cabeçalhos de gateway continuam funcionando. O endereço e a chave não podem ser editados em uma conexão existente, então, se um deles mudou, desconecte, conecte novamente e atualize LINGO_WEBHOOK_URL com a nova webhook URL.

Próximos passos#