Poner en cola la traducción en segundo plano de todos los documentos publicados de uno o más esquemas de componentes a un conjunto de idiomas de destino. Los resultados se insertan o actualizan en la tabla translations a medida que se completa cada traducción.

Endpoint: POST /translation Autenticación: JWT de tipo Bearer (WorkOS)

Cuerpo de la solicitud

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

* Proporcione schemaNames o schemaName.

Solo se tienen en cuenta los documentos publicados con contenido publicado no nulo.

Respuesta

{
  "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"
}

Devuelve:

• 202 Accepted cuando las traducciones se ponen en cola
• 200 OK cuando todas las traducciones ya están actualizadas
• el trabajo activo existente cuando ya se está ejecutando una solicitud idéntica

Los posibles estados del trabajo son:

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

Omitir traducciones actualizadas

Cada par documento-idioma almacena un hash SHA-256 del contenido publicado del documento de origen.

Una traducción se omite cuando su hash de origen almacenado coincide con el contenido publicado actual. Esto permite llamar repetidamente al endpoint sin volver a traducir contenido que no ha cambiado.

Si el contenido publicado cambia mientras hay un trabajo equivalente activo, el servicio rechaza la nueva solicitud. Vuelva a enviarla después de que finalice el trabajo activo.

Comportamiento del procesamiento

La traducción se ejecuta de forma asíncrona después de la respuesta inicial.

• El trabajo se procesa con concurrencia limitada.
• Los fallos transitorios se reintentan con retroceso progresivo.
• Los resultados correctos se conservan a medida que se completan.
• Los fallos individuales de inferencia o persistencia se registran en el trabajo.
• Un trabajo parcialmente correcto finaliza con completed_with_errors.

Ejemplo

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"]
  }'

Errores

• 400 Bad Request — faltan esquemas o idiomas, un idioma no es compatible o el lote supera el límite configurado
• 401 Unauthorized — falta el token de tipo bearer o no es válido
• 409 Conflict — hay trabajo coincidente activo, pero el contenido de origen publicado ha cambiado
• 500 Internal Server Error — no se pudieron preparar los documentos de origen o falló una operación de base de datos

Obtener trabajo de traducción

Consultar el progreso más reciente de un trabajo de traducción.

Endpoint: GET /translation-jobs/{job_id} Autenticación: JWT de tipo Bearer (WorkOS)

Respuesta

La respuesta utiliza el mismo objeto de trabajo que devuelve POST /translation, con el estado y los recuentos de progreso actualizados.

{
  "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"
}

Ejemplo

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

Errores

• 401 Unauthorized — falta el token de tipo bearer o no es válido
• 404 Not Found — el trabajo no existe o ya no se conserva

Actualmente, los trabajos de traducción se conservan en memoria. El estado del trabajo se pierde cuando se reinicia el servicio de traducción, y las implementaciones con varias instancias requieren enrutamiento persistente.