Enfileira a tradução em segundo plano de todos os documentos publicados de um ou mais esquemas de componentes para um conjunto de idiomas de destino. Os resultados são inseridos ou atualizados na tabela translations à medida que cada tradução é concluída.

Endpoint: POST /translation Autenticação: JWT Bearer (WorkOS)

Corpo da solicitação

{
  "websiteId": "<uuid>",
  "schemaNames": ["post", "hero"],
  "languages": ["fr", "es", "de"]
}

• Forneça schemaNames ou schemaName.

Somente documentos publicados com conteúdo publicado não nulo são considerados.

Resposta

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es", "de"],
  "status": "queued",
  "documents_processed": 12,
  "translations_scheduled": 30,
  "translations_skipped": 6,
  "translations_completed": 0,
  "translations_failed": 0,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:00:00Z"
}

Retorna:

• 202 Accepted quando as traduções são enfileiradas
• 200 OK quando todas as traduções já estão atualizadas
• o job ativo existente quando uma solicitação idêntica já está em execução

Os possíveis status do job são:

• preparing
• queued
• running
• completed
• completed_with_errors
• failed

Ignorando traduções atualizadas

Cada par documento-idioma armazena um hash SHA-256 do conteúdo publicado do documento de origem.

Uma tradução é ignorada quando o hash de origem armazenado corresponde ao conteúdo publicado atual. Isso permite chamar o endpoint repetidamente sem traduzir novamente conteúdo que não foi alterado.

Se o conteúdo publicado mudar enquanto um job equivalente estiver ativo, o serviço rejeitará a nova solicitação. Envie-a novamente após a conclusão do job ativo.

Comportamento do processamento

A tradução é executada de forma assíncrona após a resposta inicial.

• O trabalho é processado com concorrência limitada.
• Falhas transitórias são repetidas com intervalo progressivo.
• Os resultados bem-sucedidos são persistidos à medida que são concluídos.
• Falhas individuais de inferência ou persistência são registradas no job.
• Um job parcialmente bem-sucedido termina com completed_with_errors.

Exemplo

curl -X POST '{TRANSLATION_API_URL}/translation' \
  -H 'Authorization: Bearer <workos-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "<uuid>",
    "schemaNames": ["post", "hero"],
    "languages": ["fr", "es"]
  }'

Erros

• 400 Bad Request — esquemas ou idiomas estão ausentes, um idioma não é compatível ou o lote excede o limite configurado
• 401 Unauthorized — o token bearer está ausente ou é inválido
• 409 Conflict — há trabalho correspondente ativo, mas o conteúdo de origem publicado mudou
• 500 Internal Server Error — não foi possível preparar os documentos de origem ou uma operação de banco de dados falhou

Obter job de tradução

Recupere o progresso mais recente de um job de tradução.

Endpoint: GET /translation-jobs/{job_id} Autenticação: JWT Bearer (WorkOS)

Resposta

A resposta usa o mesmo objeto de job retornado por POST /translation, com status e contagens de progresso atualizados.

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es"],
  "status": "running",
  "documents_processed": 12,
  "translations_scheduled": 24,
  "translations_skipped": 0,
  "translations_completed": 16,
  "translations_failed": 1,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:01:30Z"
}

Exemplo

curl '{TRANSLATION_API_URL}/translation-jobs/<job-id>' \
  -H 'Authorization: Bearer <workos-jwt>'

Erros

• 401 Unauthorized — o token bearer está ausente ou é inválido
• 404 Not Found — o job não existe ou não é mais mantido

Atualmente, os jobs de tradução são mantidos na memória. O status do job é perdido quando o serviço de tradução é reiniciado, e as implantações com várias instâncias exigem roteamento persistente.