Mettre en file d’attente la traduction en arrière-plan de tous les documents publiés provenant d’un ou plusieurs schémas de composants vers un ensemble de langues cibles. Les résultats sont insérés ou mis à jour dans la table translations à mesure que chaque traduction est terminée.

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

Corps de la requête

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

* Fournir soit schemaNames, soit schemaName.

Seuls les documents publiés dont le contenu publié n’est pas nul sont pris en compte.

Réponse

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

Renvoie :

• 202 Accepted lorsque les traductions sont mises en file d’attente
• 200 OK lorsque toutes les traductions sont déjà à jour
• le job actif existant lorsqu’une requête identique est déjà en cours

Les états possibles d’un job sont :

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

Ignorer les traductions à jour

Chaque paire document-langue stocke un hachage SHA-256 du contenu publié du document source.

Une traduction est ignorée lorsque son hachage source stocké correspond au contenu publié actuel. Cela permet d’appeler l’endpoint à plusieurs reprises sans retraduire le contenu inchangé.

Si le contenu publié change alors qu’un job équivalent est actif, le service rejette la nouvelle requête. Soumettez-la à nouveau une fois le job actif terminé.

Comportement du traitement

La traduction s’exécute de manière asynchrone après la réponse initiale.

• Le travail est traité avec une concurrence limitée.
• Les échecs temporaires font l’objet de nouvelles tentatives avec un délai progressif.
• Les résultats réussis sont enregistrés au fur et à mesure de leur achèvement.
• Les échecs individuels d’inférence ou de persistance sont enregistrés dans le job.
• Un job partiellement réussi se termine avec completed_with_errors.

Exemple

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

Erreurs

• 400 Bad Request — des schémas ou des langues sont manquants, une langue n’est pas prise en charge ou le lot dépasse la limite configurée
• 401 Unauthorized — le jeton bearer est manquant ou invalide
• 409 Conflict — un traitement correspondant est actif, mais le contenu source publié a changé
• 500 Internal Server Error — les documents sources n’ont pas pu être préparés ou une opération de base de données a échoué

Obtenir un job de traduction

Récupérer la progression la plus récente d’un job de traduction.

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

Réponse

La réponse utilise le même objet de job que celui renvoyé par POST /translation, avec un état et des compteurs de progression mis à jour.

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

Exemple

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

Erreurs

• 401 Unauthorized — le jeton bearer est manquant ou invalide
• 404 Not Found — le job n’existe pas ou n’est plus conservé

Les jobs de traduction sont actuellement conservés en mémoire. L’état du job est perdu lorsque le service de traduction redémarre, et les déploiements à plusieurs instances nécessitent un routage persistant.