O seu conteúdo muda e, de repente, tem de chegar a todos os idiomas em que disponibiliza o seu produto. Um módulo de formação recebe uma nova lição. Uma entrada no CMS é guardada. Uma descrição de produto é editada. A tradução tem de ser distribuída por alemão, francês, japonês e mais uma dúzia de idiomas — e a sua aplicação não deve ficar bloqueada enquanto isso acontece.
A API de localização assíncrona foi criada exatamente para esse momento: um pedido, todos os idiomas, resultados à medida que chegam. Faz POST do seu conteúdo uma vez com os idiomas de destino, recebe um 202 de imediato e a plataforma traduz cada idioma como um trabalho em segundo plano independente. Mantém o seu glossário, a voz da marca e a configuração do modelo — o mesmo motor que a API síncrona utiliza — e deixa de ter de gerir novas tentativas.
Nesta página
O problema#
Plataformas de formação, sistemas de gestão de conteúdos e ferramentas de e-learning precisam frequentemente de traduzir conteúdo para dezenas de línguas no momento em que é criado ou atualizado. A API de localização síncrona funciona, mas obriga a um compromisso quando se escala.
Pense num módulo de formação criado em inglês que tem de chegar a formandos em 14 línguas. Com a API síncrona, tem duas opções — e ambas têm um custo:
Fazer 14 chamadas em paralelo — um pedido por idioma de destino, cada um com a mesma payload de origem. Pode apresentar cada língua à medida que chega, mas está a gerir 14 viagens de ida e volta pela rede com dados redundantes, e a lógica de novas tentativas fica a seu cargo quando uma delas falha.
Traduzir as 14 numa única chamada síncrona — menos viagens de ida e volta, mas agora tem de esperar pelo idioma mais lento antes de poder apresentar qualquer um deles.
De uma forma ou de outra, a sua aplicação fica ocupada enquanto as traduções são processadas. Se o seu servidor reiniciar a meio, as traduções em curso perdem-se. Se uma língua falhar, o tratamento de falhas parciais fica a seu cargo. E nenhuma destas abordagens dá aos seus utilizadores um sinal claro de que as traduções estão em curso.
A API assíncrona elimina esse compromisso. Um pedido cria um grupo de trabalhos com um trabalho por idioma de destino. Cada trabalho é executado independentemente através do seu motor de localização como um workflow durável em segundo plano — por isso, um reinício do seu lado não faz perder nada, porque o trabalho não está a ser executado no seu processo. Os resultados são entregues por idioma no momento em que cada um termina. A sua aplicação mantém-se responsiva. As falhas ficam isoladas. A plataforma trata das novas tentativas e da entrega.
Um idioma, e pode esperar um segundo? Use sync.
A API assíncrona justifica-se quando tem muitos idiomas, conteúdo longo ou uma UI que deve mostrar progresso. Se precisar de um único par de idiomas e puder esperar por uma viagem de ida e volta, o endpoint Localize síncrono é a opção mais simples — um pedido, os dados traduzidos de volta na resposta, sem necessidade de manter um endpoint de webhook. Recorra à assíncrona quando o trabalho for demasiado grande, demasiado lento ou envolver idiomas a mais para bloquear.
Como funciona#
São três passos, e apenas o primeiro acontece no seu ciclo de pedido/resposta. Os outros dois acontecem na plataforma, ao seu próprio ritmo.
Submeta um pedido
Faça POST do seu conteúdo e dos idiomas de destino para /jobs/localization. A API valida a payload, cria um grupo de trabalhos com um trabalho por idioma e devolve 202 com o ID do grupo e um resumo dos trabalhos. A sua aplicação pode continuar de imediato — nada é traduzido dentro desta chamada. Consulte Criar trabalhos para ver a estrutura completa do pedido e da resposta.
A plataforma processa cada idioma de forma independente
Cada trabalho é executado através do seu motor de localização por meio de um workflow durável em segundo plano, aplicando a mesma seleção de modelo, glossário, voz da marca e instruções que a API síncrona. Cada trabalho pode, opcionalmente, passar por uma pipeline com fases de pré-edição, revisão humana, pós-edição, reformulação e retrotradução. Um trabalho passa de queued para processing e depois para um estado terminal: completed, completed_with_warnings ou failed — e o resultado de um idioma nunca bloqueia o de outro.
Receba os resultados à medida que chegam
No momento em que um idioma fica concluído, a plataforma entrega o respetivo resultado ao seu URL de webhook. Para progresso em tempo real na sua UI — um contador "3 de 14 prontos" que se atualiza à medida que os trabalhos ficam concluídos — ligue-se ao WebSocket do grupo. Se preferir ir buscar os dados, faça polling ao grupo em intervalos regulares.
Autenticação
Todos os pedidos — REST e WebSocket — são autenticados com o seu cabeçalho X-API-Key. As chaves são limitadas à organização e dão acesso a todos os motores da organização. Consulte Authentication para os detalhes e API Keys para criar uma.
O modelo de grupo de trabalhos#
Uma submissão produz um grupo que contém um trabalho por idioma de destino. Esta estrutura é todo o modelo mental, e é isso que torna as perguntas difíceis mais fáceis de responder.
Um leitor mais cético já estará a fazer a lista: o que acontece quando um idioma falha, e o que acontece à minha aplicação enquanto tudo isto está em curso? O modelo de grupo responde às duas perguntas.
- As falhas ficam isoladas, porque cada idioma é o seu próprio trabalho. Se o alemão for concluído com sucesso e o japonês falhar, a tradução em alemão é entregue normalmente e o trabalho em japonês transporta o seu próprio
errorMessage. O grupo reportapartial, e o que foi concluído com sucesso continua a ser entregue. Uma falha num idioma não pode reverter outro que já tenha sido concluído. A semântica completa dos estados está em Acompanhar um grupo de trabalhos. - O trabalho em curso sobrevive a um reinício, porque não é executado no seu processo. Cada trabalho é um workflow durável em segundo plano na plataforma. Se o seu servidor reiniciar, nada do que está em curso se perde — volta a ligar-se ou faz polling, e o grupo está exatamente onde o deixou.
- O grupo é um modelo de progresso que pode ligar a uma UI. Guarde o
groupIddo202e depois alimente um indicador de progresso a partir das entregas por webhook ou dos snapshots de WebSocket. "3 de 14 línguas prontas" é um contador sobre os trabalhos dependentes do grupo.
O custo real deste modelo: assume uma pequena camada de integração que a chamada síncrona não exige. Para receber resultados, mantém um endpoint HTTPS de webhook ou uma ligação WebSocket no servidor, e trata cada idioma à medida que chega em vez de ler os dados traduzidos diretamente de uma única resposta. Em troca, a plataforma trata das novas tentativas, do isolamento de falhas e da entrega — e a sua aplicação nunca bloqueia à espera de uma tradução.
É exatamente esta a troca para a qual a API assíncrona foi concebida: um pedido, todos os idiomas, resultados à medida que chegam. As páginas seguintes são os verbos dessa frase.
