Payload CMS

Traduza campos localizados do Payload 3, preserve a estrutura dos recursos e escolha como as alterações na origem chegam aos idiomas de destino.

O Payload já reserva, em cada campo localizado, um espaço para as diferentes versões linguísticas. A ligação ao Lingo.dev lê os campos de origem selecionados, traduz o seu conteúdo através de um motor de localização e grava os resultados nos mesmos recursos, nos idiomas de destino. As coleções, os globais e a publicação continuam a ser geridos no Payload.

Na navegação do Studio 2.5, abra Studio 2.5 → Integrações em vez de Definições → Integrações. Os links existentes de ligação e configuração continuam a funcionar.

Comece com um recurso e uma sincronização manual. Depois de verificar o resultado, adicione notificações de alterações na origem se pretender que a tradução acompanhe automaticamente a edição.

A integração com o Payload CMS requer o plano Enterprise. Consulte os preços para conhecer a disponibilidade atual. Em Definições → Integrações, surge a indicação Indisponível no seu plano junto ao Payload quando a organização precisa de um plano que dê acesso à integração.

Preparar o Payload e um utilizador de serviço #

Utilize o Payload 3 com a localização configurada. A tradução de texto formatado é compatível com o editor Lexical, mas não com o antigo editor Slate. A sua instância tem de estar acessível ao Lingo.dev através de HTTPS.

Crie um utilizador de serviço numa coleção de autenticação com useAPIKey: true, normalmente users. Conceda-lhe acesso de leitura e atualização a todas as coleções ou globais que pretenda traduzir. As gravações são atribuídas a este utilizador. Se um gateway exigir cabeçalhos adicionais, forneça-os ao estabelecer a ligação e mantenha os respetivos valores em segredo.

Faça corresponder o idioma de origem da ligação ao localization.defaultLocale do Payload, que o plugin monitoriza para detetar alterações. Os códigos de origem e destino têm de corresponder exatamente aos códigos configurados no Payload: en e en-US identificam idiomas diferentes. Escolha um motor de localização acessível na organização do Lingo.dev associada à ligação. Se não conseguir adicionar a ligação, verifique as permissões da sua organização e se esta tem direito a criar ligações.

Ligar a instância e disponibilizar o respetivo esquema #

Abra Definições → Integrações e selecione Ligar junto ao Payload CMS. Introduza um nome para a ligação, o endereço raiz da instância, a coleção de autenticação, a chave de API de serviço e quaisquer cabeçalhos do gateway. Selecione Ligar para verificar o acesso e guardar a ligação. Guarde o URL do webhook apresentado de seguida para as notificações automáticas.

Instale o plugin no projeto Payload:

bash
pnpm add @lingo.dev/payloadcms

Adicione lingo ao array plugins existente. Este excerto mostra a configuração do plugin; mantenha as coleções, os globais, a localização e os restantes plugins do seu projeto:

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

export default buildConfig({
  plugins: [
    lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
  ],
});

O plugin regista sempre GET /api/lingo/schema. O Lingo.dev utiliza este ponto de acesso para identificar os campos localizados. Pode criar uma ligação antes de instalar o plugin, mas a tradução requer o ponto de acesso do esquema.

Para ativar as notificações automáticas, copie o URL do webhook da ligação para a variável de ambiente LINGO_WEBHOOK_URL do Payload. Trate-o como uma credencial secreta: quem tiver o URL pode enviar pedidos de notificação. Volte a implementar o Payload depois de alterar o plugin ou o ambiente. Para traduzir apenas manualmente, omita webhookUrl; o plugin continuará a disponibilizar o esquema.

No Studio, selecione a instância em Ligadas e, em seguida, selecione Configurar. Escolha o motor de localização, os idiomas de origem e destino e o modo de gravação dos resultados. Selecione Continuar e escolha as coleções e os globais a traduzir. Os modos de publicação são descritos abaixo.

Traduzir um recurso #

Escolha uma coleção ou um global que contenha um campo de texto localizado curto e selecione um idioma de destino. Anote os valores atuais de origem e destino no Payload antes de executar Sincronizar.

Selecione o modo de acordo com o resultado de publicação pretendido:

ModoOrigem e gravação dos resultados
RascunhoLê o conteúdo de origem em rascunho e grava os campos traduzidos como rascunhos para revisão no Payload.
PublicarProcessa alterações publicadas e grava traduções publicadas.

O Payload mantém um único rascunho partilhado por documento e publica-o na íntegra. Por isso, gravar uma tradução num documento já publicado que tenha alterações por publicar também publicaria essas alterações. Nesses casos, o modo Publicar deixa o documento inalterado e assinala a tradução como falhada. Publique as alterações ou reponha a versão publicada no Payload e, em seguida, execute novamente a Sincronização. Para ver essas alterações, o utilizador associado à chave de API precisa de acesso readVersions a todas as versões das coleções e dos elementos globais selecionados; se esse acesso estiver sujeito a filtros, o modo Publicar deixa os respetivos documentos publicados inalterados. Se um documento nunca tiver sido publicado, esta verificação é ignorada: o modo Publicar grava a tradução no documento, que continua como rascunho. A verificação é feita imediatamente antes de cada gravação, pelo que um rascunho guardado entretanto pode ainda ser publicado com a tradução. Evite guardar rascunhos de documentos enquanto uma sincronização estiver a gravar nesses documentos e verifique o respetivo estado de publicação no final. O comportamento dos rascunhos também depende da configuração do Payload; ao testar uma atualização, verifique a versão atualmente publicada.

Execute Sincronizar, abra a respetiva execução de workflow e verifique o próprio campo de destino no Payload. Confira a redação, as ligações, a estrutura do texto formatado, o idioma e o estado de publicação. Em seguida, leia o conteúdo no site que o utiliza. Estabelecer a ligação, por si só, não traduz o catálogo.

A primeira sincronização preserva as traduções existentes que estejam completas, sem as substituir. Preenche os campos em falta, incluindo aqueles cujo valor atual apenas repete o valor predefinido do Payload. Se um campo tiver sido preservado, compare o respetivo valor com esse estado antes de pedir a sua substituição.

Selecionar recursos e campos #

As tabelas Coleções e Globais têm interruptores Sincronizar cuja definição é persistente. Selecionar uma coleção abrange os respetivos documentos; selecionar um global abrange esse recurso. As ações do cabeçalho processam os recursos ativados. Quando estão disponíveis ações sobre as linhas selecionadas, estas colocam o âmbito selecionado na fila sem alterar a seleção persistente da ligação.

Nesses recursos, o esquema seleciona os campos localizados text, textarea e richText do Lexical. Também percorre o texto em grupos, arrays, blocos e separadores localizados, incluindo blocos de texto formatado aninhados e em linha.

Os campos não localizados e os valores estruturais, como id, blockType e blockName, ficam fora do texto a traduzir. Os campos de seleção, números, relações, carregamentos, código e JSON arbitrário não passam a ser traduzíveis só porque a respetiva coleção foi selecionada. Para incluir outro campo de texto, configure a sua localização no Payload e volte a implementar o projeto.

O processamento do Lexical preserva o contexto das frases entre elementos com formatação em linha e ligações e, em seguida, reconstrói a árvore com as respetivas ligações, conteúdos multimédia e blocos. Teste um documento representativo antes de alargar o âmbito, sobretudo se o seu projeto utilizar campos personalizados ou extensões do editor.

Manter as traduções alinhadas com as alterações na origem #

Com um URL de webhook e um idioma predefinido configurados, o plugin envia notificações após alterações no idioma de origem. Cada notificação contém uma referência ao recurso, não o corpo do documento. O Lingo.dev volta a ler o conteúdo com as credenciais de serviço guardadas, aplica o âmbito e o modo da ligação e agrupa as notificações próximas no tempo antes de as processar.

As gravações nos idiomas de destino não desencadeiam outra tradução. As falhas nas notificações também não impedem quem edita de guardar o conteúdo, pelo que uma gravação bem-sucedida, por si só, não confirma a entrega da notificação. Se uma alteração não tiver sido detetada, consulte o histórico de execuções e utilize Sincronizar manualmente para reconciliar o conteúdo. As gravações de rascunhos são relevantes no modo Rascunho; uma gravação num idioma de destino ou num recurso fora do âmbito não conta como alteração na origem para esta ligação.

Utilize Sincronizar para processar alterações na origem e conteúdo em falta no destino. Esta ação compara o conteúdo com a referência disponível. Quando um artefacto de origem anterior não está disponível, a recuperação pode regenerar o conteúdo afetado; por isso, verifique as diferenças em vez de presumir que todas as edições manuais serão preservadas. Depois de adicionar um idioma de destino, execute Sincronizar para o preencher.

Utilize Retraduzir quando pretender substituir as traduções selecionadas, incluindo os campos editados manualmente. Por exemplo, uma alteração significativa nas instruções do motor de localização pode justificar novos resultados, mesmo sem alterações na origem. Os pedidos ficam em fila, a aguardar que a execução ativa da ligação termine; submeter repetidamente a mesma ação não a faz terminar mais depressa.

Recuperar um documento alterado ou parcialmente gravado #

A etapa de gravação dos resultados volta a ler o conteúdo de origem. Se alguém o tiver alterado após o planeamento, o documento é ignorado para evitar aplicar os valores traduzidos a uma revisão ou a uma ordem dos elementos do array diferente. Uma sincronização posterior reconcilia o novo conteúdo de origem.

As execuções falhadas ou canceladas preservam as gravações bem-sucedidas. Em Execuções de workflow, distinga o trabalho concluído, atualizado, ignorado, falhado e cancelado e verifique os recursos afetados antes de tentar novamente. Parar cancela o trabalho ativo quando essa opção está disponível; não reverte os campos já gravados. Um resultado com o estado atualizado significa que não havia alterações selecionadas para processar.

Se os resultados nunca aparecerem, verifique o ponto de acesso do esquema, a localização e o tipo dos campos, as permissões de leitura e atualização do utilizador de serviço, o código exato do idioma, a seleção de recursos para sincronização, o modo e a configuração de ambiente do webhook. Resolva qualquer problema de acesso à instância ou de rejeição da chave antes de pedir uma retradução.

Alterar as definições ou desligar #

Altere a seleção de recursos, os idiomas, o motor de localização e o modo no Studio. Mude o nome da ligação ou faça a gestão das respetivas credenciais em Definições → Integrações. Estas alterações preservam o URL do webhook.

Para substituir a chave de API, abra a ligação em Definições → Integrações e selecione Substituir chave. Introduza uma chave da mesma coleção de autenticação e volte a introduzir todos os cabeçalhos personalizados de que a instância ainda precisa; os cabeçalhos fornecidos substituem os que estavam guardados.

Alterar o endereço da instância requer uma nova ligação. Configure o respetivo âmbito de tradução e atualize o ambiente do Payload com o novo URL do webhook antes de voltar a depender das notificações automáticas.

Desligar remove o histórico local e o estado de sincronização da ligação e interrompe futuras leituras e gravações. O conteúdo traduzido existente permanece no Payload. Remova o valor antigo da variável de ambiente do webhook ou o respetivo hook e revogue separadamente a chave de serviço se já não for necessária.

Uma nova ligação estabelece uma nova referência. A primeira sincronização preserva as traduções existentes elegíveis e preenche as lacunas; não restaura o histórico local de execuções de uma ligação anterior. Verifique essa primeira execução como faria com qualquer nova ligação.