Queue background translation of all published documents from one or more component schemas into a set of target languages. Results are upserted into the translations table as each translation completes.

Endpoint: POST /translation Auth: Bearer JWT (WorkOS)

Request body

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

* Provide either schemaNames or schemaName.

Only published documents with non-null published content are considered.

Response

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

Returns:

• 202 Accepted when translations are queued
• 200 OK when every translation is already current
• the existing active job when an identical request is already running

Possible job statuses are:

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

Skipping current translations

Each document-language pair stores a SHA-256 hash of the source document’s published content.

A translation is skipped when its stored source hash matches the current published content. This allows the endpoint to be called repeatedly without retranslating unchanged content.

If published content changes while an equivalent job is active, the service rejects the new request. Submit it again after the active job finishes.

Processing behavior

Translation runs asynchronously after the initial response.

• Work is processed with bounded concurrency.
• Transient failures are retried with backoff.
• Successful results are persisted as they complete.
• Individual inference or persistence failures are recorded on the job.
• A partially successful job finishes with completed_with_errors.

Example

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

Errors

• 400 Bad Request — schemas or languages are missing, a language is unsupported, or the batch exceeds the configured limit
• 401 Unauthorized — bearer token is missing or invalid
• 409 Conflict — matching work is active, but the published source content changed
• 500 Internal Server Error — source documents could not be prepared or a database operation failed

Get translation job

Retrieve the latest progress for a translation job.

Endpoint: GET /translation-jobs/{job_id} Auth: Bearer JWT (WorkOS)

Response

The response uses the same job object returned by POST /translation, with updated status and progress counts.

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

Example

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

Errors

• 401 Unauthorized — bearer token is missing or invalid
• 404 Not Found — the job does not exist or is no longer retained

Translation jobs are currently retained in memory. Job status is lost when the translation service restarts, and multi-instance deployments require sticky routing.