Metti in coda la traduzione in background di tutti i documenti pubblicati provenienti da uno o più schemi di componente in un insieme di lingue di destinazione. I risultati vengono inseriti o aggiornati (upsert) nella tabella translations al completamento di ciascuna traduzione.

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

Corpo della richiesta

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

* Fornisci schemaNames oppure schemaName.

Sono presi in considerazione solo i documenti pubblicati con contenuto pubblicato non nullo.

Risposta

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

Restituisce:

• 202 Accepted quando le traduzioni vengono messe in coda
• 200 OK quando ogni traduzione è già aggiornata
• il job attivo esistente quando è già in corso una richiesta identica

Gli stati possibili del job sono:

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

Ignorare le traduzioni correnti

Ogni coppia documento-lingua memorizza un hash SHA-256 del contenuto pubblicato del documento sorgente.

Una traduzione viene ignorata quando l'hash del sorgente memorizzato coincide con il contenuto pubblicato corrente. Ciò consente di chiamare ripetutamente l'endpoint senza ritradurre contenuti invariati.

Se il contenuto pubblicato cambia mentre è attivo un job equivalente, il servizio rifiuta la nuova richiesta. Invia nuovamente la richiesta dopo che il job attivo è terminato.

Comportamento dell'elaborazione

• Il lavoro viene elaborato con concorrenza limitata.
• I guasti transitori vengono ripetuti con backoff.
• I risultati riusciti vengono salvati man mano che si completano.
• I singoli errori di inferenza o di persistenza vengono registrati sul job.
• Un job parzialmente riuscito termina con completed_with_errors.

Esempio

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

Errori

• 400 Bad Request — gli schemi o le lingue mancano, una lingua non è supportata oppure il batch supera il limite configurato
• 401 Unauthorized — il bearer token è mancante o non valido
• 409 Conflict — è attivo un lavoro corrispondente, ma il contenuto sorgente pubblicato è cambiato
• 500 Internal Server Error — non è stato possibile preparare i documenti sorgente oppure un'operazione sul database non è riuscita

Recuperare un job di traduzione

Recupera l'avanzamento più recente per un job di traduzione.

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

Risposta

La risposta utilizza lo stesso oggetto job restituito da POST /translation, con stato e conteggi di avanzamento aggiornati.

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

Esempio

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

Errori

• 401 Unauthorized — il bearer token è mancante o non valido
• 404 Not Found — il job non esiste oppure non è più conservato

I job di traduzione vengono attualmente mantenuti in memoria. Lo stato del job viene perso quando il servizio di traduzione si riavvia e le distribuzioni multiistanza richiedono un instradamento persistente (sticky routing).