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á.
A integração com o Payload é ativada por organização. Se não a encontrar em Definições -> Integrações, fale connosco e ativamo-la por si.
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: truena sua coleção de autenticação (normalmenteusers), 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.
Os códigos de idioma têm de corresponder à configuração do seu Payload
Os idiomas que selecionar na Lingo.dev têm de 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 o idioma cujas alterações o plugin monitoriza.
Ligue a sua instância Payload#
Abra a integração
Vá a Definições -> Integrações e clique em Connect em Payload CMS.
Introduza os dados da sua instância
| Campo | O que introduzir |
|---|---|
| Nome da ligação | Uma etiqueta como Production ou Staging |
| URL base do Payload | O URL raiz da sua instância, por exemplo https://cms.example.com. Apenas HTTPS |
| Slug da Auth Collection | A collection a que pertence a chave de API do seu serviço, normalmente users |
| Chave de API | A chave de API do utilizador de serviço |
| Cabeçalhos personalizados | Opcional. Enviado em todos os pedidos para a sua instância. |
A Lingo.dev verifica a chave na sua instância antes de avançar.
Escolha o que traduzir
| Definição | O que faz |
|---|---|
| Collections e Globals | Assinale as que quer traduzir. Uma linha marcada como No read + update fica desativada até o utilizador de serviço receber acesso |
| Idioma de origem | O idioma em que os seus editores escrevem. Use o defaultLocale do seu Payload |
| Idiomas de destino | Os idiomas para os quais traduzir |
| Motor | O motor de localização que traduz este conteúdo |
| Traduzir gravações de rascunho | Desativado, traduz apenas alterações publicadas. Ativado, traduz também gravações em rascunho e mantém as traduções como rascunhos |
Instale o plugin
O último passo mostra o seu URL de webhook. Copie-o agora. Só é mostrado uma vez. Guarde-o como LINGO_WEBHOOK_URL no ambiente do seu 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,
}),
],
});Volte a fazer deploy do Payload. A partir daí, todas as alterações publicadas no idioma de origem são enviadas para a Lingo.dev para tradução.
O que faz o plugin
Isto adiciona um endpoint GET /api/lingo/schema que diz à Lingo.dev quais dos seus campos são texto localizado, e um hook que notifica a Lingo.dev quando um documento ou global muda. O âmbito, os idiomas e o motor ficam no dashboard, para os poder alterar sem voltar a fazer deploy. Omita webhookUrl para ignorar o hook e iniciar todas as traduções a partir do dashboard.
Escolha o que é traduzido#
A página da ligação tem três separadores: Collections, Globals e Runs.
O âmbito é definido por collection e por global. Todos os documentos de uma collection selecionada ficam abrangidos. Para alterar o âmbito, os idiomas, o motor ou a definição de rascunho, clique em Edit configuration no cabeçalho da página. As alterações aplicam-se à execução seguinte sem ser necessário novo deploy.
Dentro de um documento, é a configuração de campos do Payload que decide o que é 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 |
| Blocos e blocos inline incorporados em rich text | Sim, os respetivos campos de texto segundo as mesmas regras |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | Não |
| Campos que não estão localizados e não têm um elemento principal localizado | Não |
id, blockType, blockName | Não |
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 configurado no plugin, sempre que guardar um documento ou global no idioma de origem, a Lingo.dev é notificada. As gravações feitas num curto espaço de tempo são agrupadas numa única execução. As gravações noutros idiomas, as gravações de rascunhos (a menos que Traduzir gravações de rascunho esteja ativado) e o conteúdo fora do seu âmbito 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 | Preencher conteúdo após a ligação inicial ou voltar a tentar após uma falha |
| Retranslate | Traduz novamente tudo na linha, do zero | Depois de alterar o glossário, a voz da marca ou as regras do seu motor |
Abra uma collection para aceder aos respetivos documentos e sincronizar um de cada vez. Ambos os separadores mostram quando cada item foi sincronizado pela última vez.
Nada é traduzido ao ligar. Para traduzir o que já tem, clique em Sync em cada collection e global. Adicionar um idioma de destino mais tarde funciona da mesma forma: o próximo Sync preenche-o.
Só pode haver uma execução em curso por ligação. Os pedidos seguintes ficam em fila de espera e arrancam por ordem. Enquanto uma linha estiver abrangida por uma execução em fila ou em curso, os respetivos botões mostram Syncing....
Retranslate substitui edições manuais
Retranslate regenera todos os campos traduzidos no seu âmbito, incluindo traduções que a sua equipa editou manualmente no Payload. Sync regenera apenas os campos cujo texto de origem mudou, por isso as edições manuais nos restantes campos são preservadas.
Acompanhe uma execução#
O separador Runs lista cada execução com o respetivo estado, gatilho (Webhook ou Manual, sync ou retranslate), hora de início e duração. Uma execução em fila ou em curso pode ser cancelada a partir da lista.
Abra uma execução para ver em que fase se encontra (leitura do Payload, tradução, escrita de volta), o progresso global, o progresso por idioma de destino e os documentos, collections e globals que abrange. Cada item liga ao admin do Payload.
| Estado | Significado |
|---|---|
| Queued | À espera da execução à sua frente |
| Running | Em curso |
| Completed | Todas as traduções foram gravadas |
| Up to date | Nada dentro do âmbito mudou desde a última execução. Não é uma falha |
| Failed | A execução foi interrompida. O motivo é mostrado no topo do detalhe da execução |
| Cancelled | Interrompida por alguém da sua equipa |
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#
Com Translate draft saves desativado, que é a predefinição, 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 de rascunho não publicadas nesse documento passam a estar online com a tradução.
Com esta opção ativada, as gravações em rascunho também iniciam execuções. A Lingo.dev lê o rascunho mais recente da origem e escreve 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.
Gerir a ligação#
Gerar um novo URL de webhook#
Abra o menu no cabeçalho da página de ligação e escolha Regenerar URL do webhook. O URL antigo deixa de funcionar de imediato. Atualize LINGO_WEBHOOK_URL e faça uma nova implementação. Editar a ligação mantém o URL.
Desligar#
Desligue em Settings -> Integrations -> Payload CMS. Isto remove a ligação, o respetivo histórico de execuções e o registo do que foi traduzido. As traduções já escritas permanecem no Payload. Depois disso, remova LINGO_WEBHOOK_URL ou o plugin da sua configuração.
Voltar a ligar significa um novo URL de webhook
Uma nova ligação recebe um novo URL de webhook, por isso atualize LINGO_WEBHOOK_URL e volte a fazer deploy antes de as execuções automáticas voltarem a funcionar. A primeira sincronização volta a ler todos os documentos dentro do âmbito, mantém as traduções que o Payload já tem e preenche as lacunas.
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 |
| Âmbito | Coleções e globais completos. Sem seleção por campo |
| Ligações | Várias por organização, uma por instância Payload |
| Execuções em simultâneo | Uma por ligação |
| URL base | Apenas HTTPS |
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 collection ou global mostra "No read + update". Dê ao utilizador de serviço acesso de leitura e atualização na configuração de acesso dessa collection e, em seguida, 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 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 collection ou global está dentro do âmbito, se a gravação foi feita no idioma de origem e se foi uma publicação e não um rascunho.
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.
A ligação mostra "Couldn't reach this Payload instance". Verifique se a instância está ativa, se a chave ainda é válida e se os cabeçalhos do gateway continuam a funcionar. Atualize a ligação em Settings -> Integrations.
