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 um espaço para as versões de cada campo localizado em diferentes idiomas. A conexão com o Lingo.dev lê os campos de origem selecionados, traduz seu conteúdo por meio de um engine de localização e grava os resultados nos mesmos recursos, nos idiomas de destino. As coleções, os globais e a publicação continuam no Payload.
No menu de navegação do Studio 2.5, acesse Studio 2.5 → Integrações em vez de Configurações → Integrações. Os links de conexão e configuração existentes continuam funcionando.
Comece com um único recurso e uma sincronização manual. Depois de conferir o resultado, adicione notificações de alterações na origem se quiser que a tradução acompanhe as edições automaticamente.
A integração com o Payload CMS requer o plano Enterprise. Consulte os preços para conferir a disponibilidade atual. Em Configurações → Integrações, o aviso Indisponível no seu plano aparece ao lado de Payload quando a organização precisa de um plano que dê acesso à integração.
Prepare o Payload e um usuário de serviço #
Use o Payload 3 com a localização configurada. A tradução de texto formatado é compatível com o editor Lexical; o antigo editor Slate não é compatível. Sua instância precisa estar acessível ao Lingo.dev por HTTPS.
Crie um usuário de serviço em uma coleção de autenticação com useAPIKey: true, geralmente users. Conceda a esse usuário acesso de leitura e atualização a todas as coleções ou globais que pretende traduzir. As gravações são atribuídas a esse usuário. Se um gateway exigir cabeçalhos adicionais, informe-os ao conectar e mantenha seus valores em sigilo.
Configure o idioma de origem da conexão para que corresponda ao localization.defaultLocale do Payload, que o plugin monitora para detectar alterações. Os códigos de origem e destino precisam ser exatamente iguais aos configurados no Payload: en e en-US identificam idiomas diferentes. Escolha um engine de localização acessível na organização do Lingo.dev conectada. Se não for possível adicionar a conexão, verifique as permissões da organização e se ela tem direito a usar conexões.
Conecte a instância e disponibilize seu esquema #
Abra Configurações → Integrações e selecione Conectar para o Payload CMS. Informe um nome para a conexão, o endereço raiz da instância, a coleção de autenticação, a chave de API de serviço e os cabeçalhos de gateway necessários. Selecione Conectar para verificar o acesso e salvar a conexão. Guarde a URL do webhook exibida em seguida para as notificações automáticas.
Instale o plugin no projeto do Payload:
pnpm add @lingo.dev/payloadcmsAdicione lingo ao array plugins existente. Este trecho mostra a configuração do plugin; mantenha as coleções, os globais, a localização e os demais plugins do seu projeto:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
plugins: [
lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
],
});O plugin sempre registra GET /api/lingo/schema. O Lingo.dev usa esse endpoint para identificar os campos localizados. Você pode criar uma conexão antes de instalar o plugin, mas o endpoint do esquema é necessário para traduzir.
Para enviar notificações automáticas, copie a URL do webhook da conexão para a variável de ambiente LINGO_WEBHOOK_URL do Payload. Trate essa URL como uma credencial secreta: quem a possui pode enviar solicitações de notificação. Faça uma nova implantação do Payload após alterar o plugin ou o ambiente. Para traduzir apenas manualmente, omita webhookUrl; o plugin continuará disponibilizando o esquema.
No Studio, selecione a instância em Conectado e depois selecione Configurar. Escolha o engine 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 estão descritos abaixo.
Traduza um recurso #
Escolha uma coleção ou um global que contenha um campo curto de texto localizado e selecione um idioma de destino. Anote os valores atuais de origem e destino no Payload antes de executar a sincronização.
Escolha o modo de acordo com o resultado de publicação desejado:
| Modo | Origem e gravação dos resultados |
|---|---|
| Rascunho | Lê o conteúdo de origem em rascunho e grava os campos traduzidos como rascunhos para revisão no Payload. |
| Publicar | Processa alterações publicadas e grava traduções publicadas. |
O Payload mantém um único rascunho compartilhado por documento e o publica por completo. Por isso, gravar uma tradução em um documento já publicado que tenha alterações ainda não publicadas também publicaria essas alterações. Nesse caso, o modo de publicação mantém o documento inalterado e sinaliza a falha na tradução. Publique as alterações ou restaure a versão publicada no Payload e execute a sincronização novamente. Para visualizar essas alterações, o usuário associado à chave de API precisa ter acesso readVersions a todas as versões das coleções e dos globais selecionados; quando esse acesso é filtrado, o modo de publicação mantém inalterados os documentos publicados dessas coleções e globais. Documentos que nunca foram publicados não passam por essa verificação: o modo de publicação grava a tradução neles, mas eles continuam como rascunho. A verificação ocorre imediatamente antes de cada gravação, então um rascunho salvo nesse intervalo ainda pode ser publicado junto com a tradução. Evite salvar rascunhos de documentos enquanto uma sincronização estiver gravando neles e confira o estado de publicação depois. O comportamento dos rascunhos também depende da configuração do Payload; ao testar uma atualização, verifique a versão que está no ar.
Execute Sincronizar, abra a execução do workflow correspondente e confira o campo de destino diretamente no Payload. Verifique o texto, os links, a estrutura do texto formatado, o idioma e o estado de publicação. Depois, leia o conteúdo no site que o utiliza. A conexão, por si só, não traduz o catálogo.
A primeira sincronização preserva as traduções existentes que estão completas, sem substituí-las. Ela preenche os campos ausentes, inclusive aqueles cujo valor atual apenas repete o padrão do Payload. Se um campo tiver sido mantido, compare seu valor com esse estado antes de solicitar uma substituição.
Selecione recursos e campos #
As tabelas Coleções e Globais têm controles de Sincronizar cuja configuração fica salva. Selecionar uma coleção inclui seus documentos; selecionar um global inclui esse recurso. As ações do cabeçalho processam os recursos habilitados. Quando há ações para as linhas selecionadas, elas colocam o escopo selecionado na fila sem alterar a seleção salva na conexão.
Nesses recursos, o esquema seleciona os campos localizados text, textarea e richText do Lexical. Ele também percorre o texto em grupos, arrays, blocos e abas localizados, incluindo blocos de texto formatado aninhados e em linha.
Campos não localizados e valores estruturais como id, blockType e blockName ficam fora do texto a traduzir. Campos de seleção, números, relacionamentos, uploads, código e JSON arbitrário não se tornam traduzíveis apenas porque a coleção foi selecionada. Para incluir outro campo de texto, configure sua localização no Payload e faça uma nova implantação.
O processamento do Lexical preserva o contexto das frases mesmo com formatação em linha e links e, depois, reconstrói a árvore com seus links, mídias e blocos. Teste um documento representativo antes de ampliar o escopo, especialmente se o projeto usar campos personalizados ou extensões do editor.
Mantenha as traduções alinhadas às alterações na origem #
Com uma URL de webhook e um idioma padrão 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 relê o conteúdo usando as credenciais de serviço armazenadas, aplica o escopo e o modo da conexão e agrupa notificações próximas no tempo antes de processá-las.
Gravações no idioma de destino não iniciam outra tradução. Falhas nas notificações também não impedem que uma edição seja salva, portanto, salvar com sucesso não basta para confirmar a entrega. Se uma alteração não tiver sido capturada, confira o histórico de execuções e use a sincronização manual para reconciliar o conteúdo. Salvamentos de rascunhos são relevantes no modo Rascunho; um salvamento no idioma de destino ou um recurso fora do escopo não conta como alteração na origem para essa conexão.
Use Sincronizar para processar alterações na origem e conteúdo ausente no destino. A ação compara o conteúdo com a referência disponível. Quando um artefato anterior da origem não está disponível, a recuperação pode gerar novamente o conteúdo afetado; por isso, confira as diferenças em vez de presumir que todas as edições manuais serão mantidas. Depois de adicionar um idioma de destino, execute a sincronização para preenchê-lo.
Use Retraduzir quando quiser substituir as traduções selecionadas, incluindo campos editados manualmente. Por exemplo, uma alteração significativa nas instruções do engine de localização pode justificar um novo resultado mesmo sem mudanças na origem. As solicitações entram na fila após a execução ativa da conexão; enviar a mesma ação repetidamente não faz com que ela termine mais rápido.
Recupere um documento alterado ou parcialmente gravado #
A etapa de gravação dos resultados relê o conteúdo de origem. Se alguém o tiver editado após o planejamento, o documento será ignorado para evitar que os valores traduzidos sejam aplicados a uma revisão ou a uma ordem de array diferente. Uma sincronização posterior reconcilia a nova origem.
Execuções com falha ou canceladas preservam as gravações bem-sucedidas. Em Execuções de workflow, diferencie os trabalhos concluídos, atualizados, ignorados, com falha e cancelados e confira os recursos afetados antes de tentar novamente. Parar cancela o trabalho ativo quando disponível; não reverte campos já gravados. Um resultado atualizado significa que não havia nenhuma alteração selecionada para processar.
Se nenhum resultado aparecer, verifique o endpoint do esquema, a localização e o tipo do campo, as permissões de leitura e atualização do usuário 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 instância inacessível ou chave rejeitada antes de solicitar uma retradução.
Altere as configurações ou desconecte #
Altere a seleção de recursos, os idiomas, o engine de localização e o modo no Studio. Renomeie a conexão ou gerencie suas credenciais em Configurações → Integrações. Essas alterações preservam a URL do webhook.
Para trocar a chave de API, abra a conexão em Configurações → Integrações e selecione Substituir chave. Informe uma chave da mesma coleção de autenticação e insira novamente todos os cabeçalhos personalizados de que a instância ainda precisa; os cabeçalhos fornecidos substituem os armazenados.
Alterar o endereço da instância exige uma nova conexão. Configure o escopo de tradução dessa conexão e atualize o ambiente do Payload com a nova URL do webhook antes de voltar a depender das notificações automáticas.
Ao desconectar, o histórico local e o estado de sincronização da conexão são removidos, e as próximas leituras e gravações são interrompidas. O conteúdo já traduzido permanece no Payload. Remova o valor antigo do webhook no ambiente ou o hook e revogue a chave de serviço separadamente se ela não for mais necessária.
Uma nova conexão estabelece uma nova referência. Sua primeira sincronização mantém as traduções existentes elegíveis e preenche as lacunas; ela não restaura o histórico local de execuções de uma conexão anterior. Confira essa primeira execução como faria com qualquer nova conexão.