Seu conteúdo muda, e agora ele precisa chegar a todos os idiomas em que seu produto está disponível. Um módulo de treinamento ganha uma nova lição. Uma entrada no CMS é salva. Uma descrição de produto é editada. A tradução precisa se desdobrar para alemão, francês, japonês e mais uma dúzia de idiomas — e seu app não deve ficar bloqueado enquanto isso acontece.
A API assíncrona de localização foi feita exatamente para esse momento: uma solicitação, todos os idiomas, resultados conforme chegam. Você faz um POST do conteúdo uma vez com os idiomas de destino, recebe um 202 imediatamente, e a plataforma traduz cada idioma como um job independente em segundo plano. Você mantém seu glossário, voz da marca e configuração de modelo — o mesmo engine que a API síncrona usa — e deixa de ser responsável pelas novas tentativas.
Nesta página
O problema#
Plataformas de treinamento, sistemas de gerenciamento de conteúdo e ferramentas de e-learning muitas vezes precisam traduzir conteúdo para dezenas de idiomas no exato momento em que ele é criado ou atualizado. A API síncrona de localização funciona, mas impõe um trade-off em escala.
Pense em um módulo de treinamento criado em inglês que precisa chegar a alunos em 14 idiomas. Com a API síncrona, você tem duas opções — e ambas têm um custo:
Disparar 14 chamadas em paralelo — uma solicitação por idioma de destino, cada uma carregando o mesmo payload de origem. Você pode renderizar cada idioma conforme ele retorna, mas precisa gerenciar 14 idas e vindas de rede com dados redundantes, e a lógica de nova tentativa fica por sua conta quando uma delas falha.
Traduzir os 14 em uma única chamada síncrona — menos idas e vindas, mas agora você precisa esperar pelo idioma mais lento antes de conseguir exibir qualquer um deles.
De qualquer forma, sua aplicação fica presa enquanto as traduções são processadas. Se o servidor reiniciar no meio do caminho, as traduções em andamento se perdem. Se um idioma falhar, o tratamento de falhas parciais fica por sua conta. E nenhuma das duas opções dá aos seus usuários um sinal claro de que as traduções estão em andamento.
A API assíncrona elimina esse trade-off. Uma solicitação cria um grupo de jobs com um job por idioma de destino. Cada job é executado de forma independente pelo seu engine de localização como um workflow durável em segundo plano — então, se o seu servidor reiniciar, nada se perde, porque o trabalho não está rodando no seu processo. Os resultados são entregues por idioma no instante em que cada um termina. Seu app continua responsivo. As falhas seguem isoladas. A plataforma cuida das novas tentativas e da entrega.
Um idioma só, e você pode esperar um segundo? Use sync.
A API assíncrona faz mais sentido quando você tem muitos idiomas, conteúdo longo ou uma UI que precisa mostrar progresso. Se você precisa de um único par de idiomas e pode esperar uma ida e volta, o endpoint síncrono Localize é a opção mais simples — uma solicitação, dados traduzidos de volta na resposta, sem precisar manter um endpoint de webhook. Recorra ao assíncrono quando o job for grande demais, lento demais ou envolver idiomas demais para bloquear.
Como funciona#
São três etapas, e só a primeira acontece no seu ciclo de solicitação/resposta. As outras duas acontecem na plataforma, no tempo dela.
Envie uma solicitação
Faça um POST do seu conteúdo e dos idiomas de destino para /jobs/localization. A API valida o payload, cria um grupo de jobs com um job por idioma e retorna 202 com o ID do grupo e um resumo dos jobs. Sua aplicação fica livre para seguir em frente imediatamente — nada é traduzido dentro dessa chamada. Consulte Criar jobs para ver o formato completo da solicitação e da resposta.
A plataforma processa cada idioma de forma independente
Cada job passa pelo seu engine de localização em 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 usa. Cada job também pode, opcionalmente, passar por um pipeline com etapas de pré-edição, revisão humana, pós-edição, reformulação e retrotradução. Um job vai de queued para processing até chegar a um estado terminal: completed, completed_with_warnings ou failed — e o resultado de um idioma nunca bloqueia o de outro.
Receba os resultados conforme cada um fica pronto
No momento em que um idioma é concluído, a plataforma entrega o resultado ao seu URL de webhook. Para progresso em tempo real na sua UI — um contador "3 de 14 prontos" que se atualiza conforme os jobs são concluídos — conecte-se ao WebSocket do grupo. Se preferir buscar os dados, consulte o grupo em intervalos regulares.
Autenticação
Toda solicitação — REST e WebSocket — é autenticada com seu cabeçalho X-API-Key. As chaves têm escopo de organização e alcançam todo engine da organização. Consulte Authentication para os detalhes e API Keys para criar uma.
O modelo de grupo de jobs#
Uma submissão gera um grupo com um job por idioma de destino. Esse formato é todo o modelo mental — e é ele que torna as perguntas difíceis respondíveis.
Um leitor mais cético já está passando pela lista: o que acontece quando um idioma falha, e o que acontece com meu app enquanto tudo isso está em andamento? O modelo de grupo responde às duas perguntas.
- As falhas ficam isoladas, porque cada idioma é um job próprio. Se o alemão for bem-sucedido e o japonês falhar, a tradução em alemão é entregue normalmente e o job em japonês carrega seu próprio
errorMessage. O grupo reportapartial, e o trabalho que deu certo ainda é entregue. Uma falha em um idioma não pode reverter outro que já foi concluído. A semântica completa de status está em Acompanhar um grupo de jobs. - O trabalho em andamento sobrevive a uma reinicialização, porque não roda no seu processo. Cada job é um workflow durável em segundo plano na plataforma. Se o seu servidor reiniciar, nada em andamento se perde — você se reconecta ou consulta novamente, e o grupo estará exatamente onde você o deixou.
- O grupo é um modelo de progresso que você pode conectar à UI. Armazene o
groupIdde202e, a partir daí, alimente um indicador de progresso com as entregas por webhook ou os snapshots do WebSocket. "3 de 14 idiomas prontos" é um contador sobre os jobs filhos do grupo.
O custo real desse modelo é simples: você assume uma pequena integração que a chamada síncrona não exige. Para receber resultados, você precisa manter um endpoint HTTPS de webhook ou uma conexão WebSocket no servidor, e processar cada idioma conforme ele chega em vez de ler os dados traduzidos diretamente de uma única resposta. Em troca, a plataforma cuida das novas tentativas, do isolamento de falhas e da entrega — e seu app nunca fica bloqueado por causa de uma tradução.
Esse é o trade-off para o qual a API assíncrona foi criada: uma solicitação, todos os idiomas, resultados conforme chegam. As próximas páginas são os verbos dessa frase.
