Payload CMS

Ligue o seu Payload CMS a um motor de localização, escolha as collections e globals a abranger, e a Lingo.dev traduz os respetivos campos localizados para os seus idiomas de destino e escreve-os de volta no Payload em cada idioma.

Funciona com projetos Payload 3 com a localização ativada e que usem o editor de texto formatado Lexical. O editor Slate mais antigo não é suportado. Os campos localizados text, textarea e richText são traduzidos. Tudo o resto no documento mantém-se tal como está.

O Payload CMS está disponível com o plano Enterprise. Se a página Ligar mostrar Payload CMS is not on your plan, fale connosco e tratamos disso.

Antes de começar#

Precisa de três coisas:

• Payload 3 com a localização configurada. Certifique-se de que os seus idiomas de origem e de destino correspondem aos idiomas definidos na configuração do Payload.
• Um utilizador de serviço com uma chave de API. Defina useAPIKey: true na sua coleção de autenticação (normalmente users), crie um utilizador para Lingo.dev e gere uma chave de API para esse utilizador no admin do Payload. O utilizador precisa de acesso de leitura e atualização a todas as collections e globals que quer traduzir.
• Um motor de localização. O respetivo glossário, voz da marca e regras orientam as traduções.

Ligue a sua instância 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 é traduzido#

A página da ligação tem quatro separadores: Collections, Globals, Execuções de fluxo de trabalho e Definições.

O âmbito é definido por coleção e por global. Os separadores Collections e Globals listam tudo o que a sua instância disponibiliza, uma linha por item, com a indicação de quando foi sincronizado pela última vez. Cada linha tem um interruptor Sync: ative-o e, a partir desse momento, todos os documentos dessa coleção, ou desse global, ficam abrangidos. A alteração é guardada no momento em que muda o interruptor e aplica-se à execução seguinte sem ser necessária uma nova implementação. O interruptor no cabeçalho da tabela ativa ou desativa o Sync para tudo na lista.

Uma linha marcada com no read + update está bloqueada: o utilizador de serviço não a consegue ler nem atualizar, por isso não pode ser traduzida. Uma linha marcada com not localized yet tem o Sync desativado.

Os idiomas, o motor e o modo podem ser alterados no separador Definições.

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

O texto formatado é traduzido como uma árvore Lexical. A formatação, as hiperligações, os ficheiros carregados e a estrutura em blocos são preservados, sendo substituído apenas o texto no interior. Uma frase dividida por texto a negrito ou por uma hiperligação é traduzida como uma única frase.

Para incluir um campo no âmbito, marque-o como localized: true no Payload e volte a fazer deploy. A execução seguinte passa a incluí-lo.

Sincronizar e retraduzir#

Execuções automáticas. Com webhookUrl definido no plugin, cada gravação de um documento ou global no idioma de origem notifica a Lingo.dev. As gravações feitas num curto intervalo de tempo são agrupadas numa única execução. As gravações noutros idiomas, as gravações em rascunho (a menos que a ligação esteja em modo Draft) e o conteúdo fora do seu âmbito são ignorados.

Execuções manuais. Dois botões, duas ações diferentes:

Ambos ficam no cabeçalho da página, onde abrangem tudo o que tem o Sync ativado. Retranslate no cabeçalho pede-lhe primeiro confirmação. Para executar apenas algumas coleções ou globals, selecione as respetivas linhas: Queue sync (N) e Queue retranslation (N) aparecem e aplicam-se apenas a essas linhas. Uma linha só pode ser selecionada depois de o respetivo interruptor Sync estar ativado.

Nada é traduzido ao ligar. Para traduzir o que já existe, clique em Sync no cabeçalho da página. Adicionar um idioma de destino mais tarde funciona da mesma forma: o Sync seguinte trata disso.

Só pode haver uma execução em curso por ligação. Os pedidos seguintes entram em fila e arrancam por ordem.

Acompanhe uma execução#

O separador Execuções de fluxo de trabalho lista todas as execuções: quando começaram, o que as desencadeou (Webhook ou Manual, e depois Sync ou Retranslate), que idiomas abrangeram, quanto tempo demoraram e qual o respetivo estado. Uma execução em fila ou em curso 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á escreveu. A mensagem de erro lista os documentos que não foram escritos, e a Sync seguinte volta a tentar escrevê-los. Se um editor guardar um documento a meio da execução, esse documento é ignorado e retomado na execução seguinte.

Onde ficam as traduções#

Cada tradução é escrita no mesmo documento ou global, no respetivo idioma de destino, de acordo com o próprio modelo de localização do Payload. Apenas os campos traduzidos são escritos. Todos os outros campos permanecem inalterados. As reescritas são executadas com o utilizador 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 um idioma de destino já contenha mantém-se e apenas os campos em falta são traduzidos. Um campo que ainda contenha o valor predefinido do Payload conta como estando em falta. Use Retranslate para substituir traduções existentes.

Rascunhos vs. Publicado#

No modo Publish, só as alterações publicadas iniciam uma execução, e as traduções são publicadas assim que são escritas. O Payload publica o documento inteiro, por isso quaisquer edições em rascunho ainda não publicadas nesse documento ficam visíveis com a tradução.

No modo Draft, as gravações em rascunho também iniciam execuções. A Lingo.dev lê o rascunho mais recente da origem e guarda cada tradução como rascunho. Nada muda para os seus leitores até alguém publicar a tradução no Payload. Use esta opção enquanto avalia a qualidade da tradução ou quando as traduções passam por revisão.

Pode alterar o modo mais tarde no separador Definições.

Gerir a ligação#

Definições#

O separador Definições mostra a instância que a ligação lê, que coleções e globals têm o Sync ativado e se a ligação está Working ou Cannot be reached. Permite alterar o nome, o idioma de origem, os idiomas de destino, o motor e o modo. Cada alteração mantém o webhook URL, por isso não é necessária uma nova implementação.

O endereço e a chave de API são definidos quando a ligação é criada e não podem ser alterados depois. Para apontar a Lingo.dev para um endereço ou chave diferentes, desligue e volte a ligar.

Desligar#

Disconnect na parte inferior do separador Definições impede a Lingo.dev de ler e escrever na instância. Isto remove a ligação, o histórico de execuções e o registo do que foi traduzido. As traduções já escritas permanecem no Payload. Depois, remova LINGO_WEBHOOK_URL ou o plugin da sua configuração.

Limites#

Resolução de problemas#

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

Uma coleção ou global mostra "no read + update". Dê ao utilizador de serviço acesso de leitura e atualização na configuração de acesso dessa coleção e, em seguida, recarregue a página da ligação. O interruptor Sync da linha é desbloqueado.

A primeira execução falha com "The Lingo plugin isn't installed". Adicione @lingo.dev/payloadcms ao plugins da configuração do seu Payload e volte a fazer deploy. A ligação funciona sem o plugin; a sincronização 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á no âmbito, se a gravação foi feita no idioma de origem e se foi uma publicação e não um rascunho, a menos que a ligação esteja em modo Draft.

Um campo não é traduzido. Não tem localized: true nem no próprio campo nem num elemento principal, ou não é um campo text, textarea ou richText.

O separador Definições mostra a ligação como Cannot be reached. Verifique se a instância está ativa, se a chave continua válida e se os cabeçalhos de gateway continuam a funcionar. O endereço e a chave não podem ser editados numa ligação existente, por isso, se algum deles tiver mudado, desligue, volte a ligar e atualize LINGO_WEBHOOK_URL com o novo webhook URL.

Passos seguintes#