Criou um grupo, recebeu um groupId de volta, e agora vários idiomas estão a ser traduzidos em paralelo. Há uma pergunta a que precisa de responder repetidamente, até o trabalho assentar: como está toda a submissão neste momento? Não idioma a idioma — o agregado. Quantos estão concluídos, quantos geraram resultado com avisos, quantos falharam, quantos continuam em execução.
É exatamente isso que este endpoint devolve. Um único poll, o estado de todos os idiomas, numa só resposta. Novo na localização assíncrona? Comece pela Visão geral da API de localização assíncrona.
Nesta página
- Obter um grupo de jobs
- Resposta
- Estados do grupo
- Com que frequência fazer polling
- Quando um idioma falha
Obter um grupo de jobs#
Recupere o estado de um grupo de jobs e de todos os jobs associados.
GET /jobs/localization/groups/:groupIdAutentique-se com a sua chave de API no cabeçalho X-API-Key, a mesma chave que usou para criar o grupo. O groupId é o ID com o prefixo ljg_ da resposta 202.
Resposta#
A resposta é um retrato da submissão inteira: o status do próprio grupo, quatro contagens e os jobs associados com os respetivos estados individuais. É este o objeto que consulta em cada poll.
{
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"status": "processing",
"sourceLocale": "en",
"totalJobs": 3,
"completedJobs": 1,
"completedWithWarningsJobs": 0,
"failedJobs": 0,
"jobs": [
{ "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
{ "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "processing", "warnings": [], "completedAt": null },
{ "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued", "warnings": [], "completedAt": null }
],
"createdAt": "2026-03-16T10:30:00.000Z"
}Os três campos de contagem para jobs terminais — completedJobs, completedWithWarningsJobs e failedJobs — somam o número de idiomas que já terminaram. O restante de totalJobs continua em queued ou processing. No retrato acima, 1 em 3 está concluído e 2 ainda estão em curso, por isso basta uma leitura das contagens para perceber que o trabalho ainda não assentou, sem ter de percorrer o array jobs. Quando essa soma atingir totalJobs, o grupo terá atingido um estado terminal.
O array warnings de cada job mostra falhas não críticas em etapas opcionais do pipeline — por exemplo, uma etapa de pré-edição ou retrotradução que não foi concluída. Um array não vazio significa que o job ainda assim produziu resultado, mas que pelo menos uma etapa opcional ficou por concluir. O próprio outputData traduzido encontra-se no job individual — obtenha-o quando estiver pronto para consultar o conteúdo de um idioma concluído.
Estados do grupo#
O status do grupo consolida os jobs associados num único valor. Faz polling até atingir um estado terminal.
| Estado do grupo | Significado |
|---|---|
pending | Grupo criado, ainda sem jobs iniciados |
processing | Pelo menos um job está em curso |
completed | Todos os jobs foram concluídos com sucesso |
completed_with_warnings | Todos os jobs produziram resultado, mas uma ou mais etapas opcionais do pipeline falharam em pelo menos um job |
partial | Alguns jobs foram concluídos, outros falharam |
failed | Todos os jobs falharam |
A distinção entre completed, completed_with_warnings e partial é precisamente a razão de ser deste endpoint: separa "todos os idiomas foram entregues" de "todos os idiomas foram entregues, alguns com aviso" e de "alguns idiomas foram entregues e outros não" — três resultados que, de outra forma, teria de reconstruir ao ler cada job. partial não é um erro; é um estado real que o grupo comunica de forma explícita para que o seu código possa tomar decisões com base nisso.
Com que frequência fazer polling#
Intervalo de polling
Para a maioria dos jobs, o processamento demora 2–8 segundos por idioma. Se estiver a fazer polling em vez de usar webhooks ou WebSocket, um intervalo de 2 segundos é um ponto de partida razoável.
O polling é a forma mais simples de acompanhar um grupo e, para um lote de curta duração, funciona perfeitamente. Mas é a opção menos forte, e vale a pena dizê-lo com clareza: cada poll implica uma ida e volta, tenha ou não havido alterações, e só sabe que um idioma ficou concluído no ciclo seguinte, não no momento em que fica pronto.
Se quiser cada resultado no instante em que estiver pronto, não faça polling — seja notificado. A plataforma entrega cada idioma concluído no seu URL de webhook à medida que termina, e uma ligação WebSocket no grupo envia um retrato completo do estado a cada alteração, para que a sua UI se atualize sem ter de perguntar. Recorra ao polling quando um endpoint de webhook ou uma ligação persistente for mais do que o job justifica; opte por push quando a latência até à sua UI importa.
Quando um idioma falha#
Uma leitura cética de "traduzir para muitos idiomas ao mesmo tempo" levanta logo a pergunta óbvia: o que acontece aos restantes quando um idioma falha? Aqui está a resposta, na própria resposta.
Cada idioma é um job independente. Se o alemão for bem-sucedido mas o japonês falhar, a tradução para alemão fica concluída e é entregue normalmente — a falha não faz rollback. O job que falhou aparece no grupo com status: "failed", failedJobs aumenta, e o grupo consolida em partial:
{
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"status": "partial",
"sourceLocale": "en",
"totalJobs": 3,
"completedJobs": 2,
"completedWithWarningsJobs": 0,
"failedJobs": 1,
"jobs": [
{ "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
{ "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:05.000Z" },
{ "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "failed", "warnings": [], "completedAt": null }
],
"createdAt": "2026-03-16T10:30:00.000Z"
}Dois idiomas foram entregues, um não, e as contagens dizem-no sem que tenha de percorrer seja o que for. Para voltar a tentar, submeta um novo pedido apenas com os idiomas que falharam e uma nova chave de idempotência. A descrição completa do erro de um idioma que falhou — o errorMessage — encontra-se no job individual; o grupo dá-lhe a contagem e o veredito.
Falhas parciais são um estado normal
partial significa exatamente o que as contagens mostram: alguns idiomas foram concluídos, outros falharam. Os idiomas concluídos já foram entregues. Não há nada para reverter nem novo consumo nos idiomas que tiveram sucesso — volta a tentar apenas o que falhou.
