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á.
A integração com Payload é ativada por organização. Se ela não aparecer em Settings -> Integrations, fale com a gente e nós ativamos para você.
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: truena sua collection de autenticação (geralmenteusers), 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.
Os códigos de idioma precisam corresponder à configuração do Payload
Os idiomas escolhidos no Lingo.dev precisam corresponder exatamente aos códigos em localization.locales. Se o Payload tiver en e de, escolha English e German, não English (United States): en-US e en são idiomas diferentes. Use o defaultLocale do seu Payload como idioma de origem, porque é esse idioma que o plugin monitora para detectar alterações.
Conecte sua instância do Payload#
Abra a integração
Vá até Settings -> Integrations e clique em Connect em Payload CMS.
Informe os dados da sua instância
| Campo | O que preencher |
|---|---|
| Nome da conexão | Um rótulo como Production ou Staging |
| URL base do Payload | A URL raiz da sua instância, por exemplo https://cms.example.com. Apenas HTTPS |
| Slug da auth collection | A collection à qual pertence sua chave de API de serviço, geralmente users |
| Chave de API | A chave de API do usuário de serviço |
| Headers personalizados | Opcional. Enviado em todas as solicitações para a sua instância |
O Lingo.dev valida a chave na sua instância antes de continuar.
Escolha o que traduzir
| Configuração | O que faz |
|---|---|
| Collections e Globals | Marque as que quer traduzir. Uma linha com No read + update continua desativada até que o usuário de serviço receba acesso a ela |
| Idioma de origem | O idioma em que seus editores escrevem. Use o defaultLocale do Payload |
| Idiomas de destino | Os idiomas para os quais traduzir |
| Engine | O engine de localização que traduz este conteúdo |
| Traduzir salvamentos de rascunho | Desativado: traduz apenas alterações publicadas. Ativado: traduz também salvamentos de rascunho e mantém as traduções como rascunho |
Instale o plugin
A última etapa mostra a URL do seu webhook. Copie agora. Ela é exibida apenas uma vez. Salve-a como LINGO_WEBHOOK_URL no ambiente do Payload, depois instale o plugin e adicione-o à sua configuração:
pnpm add @lingo.dev/payloadcmsimport { 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,
}),
],
});Faça o redeploy do Payload. A partir daí, toda alteração publicada no idioma de origem será enviada ao Lingo.dev para tradução.
O que o plugin faz
Ele adiciona um endpoint GET /api/lingo/schema que informa ao Lingo.dev quais campos são textos localizados, além de um hook que avisa o Lingo.dev quando um documento ou global muda. Escopo, idiomas e engine ficam no dashboard, então você pode alterá-los sem fazer redeploy. Deixe webhookUrl de fora para pular o hook e iniciar todas as traduções pelo dashboard.
Escolha o que será traduzido#
A página da conexão tem três abas: Collections, Globals e Runs.
O escopo é definido por collection e por global. Todos os documentos de uma collection selecionada entram na cobertura. Para alterar escopo, idiomas, engine ou a configuração de rascunho, clique em Edit configuration no cabeçalho da página. As mudanças passam a valer na próxima execução, sem precisar de redeploy.
Dentro de um documento, é a configuração de campos do Payload que determina o que será traduzido:
| Campo | Traduzido |
|---|---|
Campos text, textarea e richText marcados como localized: true | Sim |
Os mesmos tipos de campo dentro de um group, array, blocks ou tabs localizado | Sim |
| Blocks e inline blocks incorporados em rich text | Sim, os campos de texto delas seguem as mesmas regras |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | Não |
| Campos que não são localizados e não têm um campo pai localizado | Não |
id, blockType, blockName | Não |
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 configurado no plugin, cada salvamento de um documento ou global no idioma de origem notifica a 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 Traduzir salvamentos de rascunho esteja ativado) e conteúdo fora do seu escopo são ignorados.
Execuções manuais. Cada linha de collection, global e documento tem dois botões:
| Botão | O que faz | Quando usar |
|---|---|---|
| Sync | Traduz apenas o que mudou desde a última execução | Para preencher conteúdo existente após conectar ou tentar de novo depois de uma falha |
| Retranslate | Traduz tudo na linha novamente, do zero | Depois de mudar o glossário, a voz da marca ou as regras do seu engine |
Abra uma collection para acessar seus documentos e sincronizar um por vez. As duas abas mostram quando cada item foi sincronizado pela última vez.
Nada é traduzido no momento da conexão. Para traduzir o que você já tem, clique em Sync em cada collection e global. Adicionar um idioma de destino depois funciona do mesmo jeito: o próximo Sync preenche esse idioma.
Só uma execução pode ficar em andamento por conexão. As solicitações seguintes entram na fila e começam em ordem. Enquanto uma linha estiver coberta por uma execução em fila ou em andamento, os botões mostrarão Syncing....
Retranslate sobrescreve edições manuais
Retranslate regenera todos os campos traduzidos dentro do escopo, inclusive traduções que sua equipe editou manualmente no Payload. Já o Sync regenera apenas os campos cujo texto de origem mudou, então as edições manuais nos demais campos são preservadas.
Acompanhe uma execução#
A aba Runs lista cada execução com status, gatilho (Webhook ou Manual, sync ou retranslate), horário de início e duração. Uma execução em fila ou em andamento pode ser cancelada por essa lista.
Abra uma execução para ver em que etapa ela está (leitura do Payload, tradução, gravação de volta), o progresso geral, o progresso por idioma de destino e os documentos, collections e globals que ela cobre. Cada item tem link para o admin do Payload.
| Status | Significado |
|---|---|
| Na fila | Aguardando a execução anterior |
| Em andamento | Em progresso |
| Concluída | Todas as traduções foram gravadas de volta |
| Atualizado | Nada dentro do escopo mudou desde a última execução. Não é uma falha |
| Falhou | A execução foi interrompida. O motivo aparece no topo dos detalhes da execução |
| Cancelada | Interrompida por alguém da sua equipe |
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#
Com Translate draft saves desativado (padrão), apenas alterações publicadas iniciam uma execução, e as traduções são publicadas assim que são gravadas. Como o Payload publica o documento inteiro, qualquer edição de rascunho ainda não publicada nesse documento também vai ao ar junto com a tradução.
Com essa opção ativada, 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 quem lê até que alguém publique a tradução no Payload. Use isso ao avaliar a qualidade das traduções ou quando elas passam por revisão.
Gerenciar a conexão#
Gerar uma nova URL de webhook#
Abra o menu no cabeçalho da página de conexão e escolha Regenerar URL do webhook. A URL antiga para de funcionar imediatamente. Atualize LINGO_WEBHOOK_URL e faça uma nova implantação. Editar a conexão mantém a URL.
Desconectar#
Desconecte em Settings -> Integrations -> Payload CMS. Isso remove a conexão, o histórico de execuções e o registro do que já foi traduzido. As traduções que já foram gravadas continuam no Payload. Depois, remova LINGO_WEBHOOK_URL ou o plugin da sua configuração.
Reconectar significa uma nova URL de webhook
Uma nova conexão recebe uma nova URL de webhook, então atualize LINGO_WEBHOOK_URL e faça redeploy antes que as execuções automáticas voltem a funcionar. A primeira sincronização relê todos os documentos dentro do escopo, mantém as traduções que o Payload já tem e preenche o que estiver faltando.
Limites#
| Limite | Detalhe |
|---|---|
| Versão do Payload | Payload 3 com localização configurada |
| Tipos de campo | Campos text, textarea e richText (apenas Lexical) marcados como localized |
| Escopo | Coleções e globais inteiros. Sem seleção por campo |
| Conexões | Vários por organização, um por instância do Payload |
| Execuções simultâneas | Um por conexão |
| URL base | Apenas HTTPS |
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 collection 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 collection e depois reabra a configuração.
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 collection ou global está no escopo, se o salvamento foi feito no idioma de origem e se foi uma publicação, não um rascunho.
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 conexão mostra "Couldn't reach this Payload instance". Verifique se a instância está no ar, se a chave ainda é válida e se os cabeçalhos do gateway continuam funcionando. Atualize a conexão em Settings -> Integrations.
