Créer un workflow de traduction par API

Traduisez les enregistrements de votre application côté serveur et conservez le lien entre chaque version linguistique acceptée et la révision source correspondante.

Lorsqu’une personne modifie une description de produit, chaque version traduite doit refléter ce changement. La réponse de l’API fournit le nouveau texte ; votre application détermine à quel enregistrement il correspond, si la source est toujours à jour et quand le rendre visible.

Ce guide prolonge une première requête de traduction pour en faire un workflow backend reproductible. Il convient aux enregistrements gérés par votre application, comme les descriptions de produits et les fiches d’aide. Les ressources statiques de l’application se prêtent souvent mieux à un workflow de fichiers en CI, car la compilation des ressources et la relecture du dépôt offrent déjà un cadre pour les valider.

Envoyer un ensemble de contenu cohérent #

Créez une tâche de localisation avec un seul document JSON intégré pour un enregistrement de produit. Regroupez les champs liés pour que le contexte puisse préciser leur fonction, et conservez des clés stables afin de retrouver les champs correspondants dans l’objet téléchargé.

Envoyez ce corps de requête à POST /v2/organizations/:orgId/localization/jobs, avec une clé API et un Idempotency-Key stable pour cette révision :

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "products/bottle.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Product listing for a reusable drinks bottle",
          "hints": {
            "$.title": ["Catalog card title"],
            "$.description": ["Short product description; do not add specifications"]
          }
        }
      },
      "source": {
        "content": {
          "title": "Insulated bottle",
          "description": "Keeps drinks cold during your commute."
        }
      }
    }
  ]
}

Conservez les identifiants d’authentification dans le backend et sélectionnez explicitement le moteur. Utilisez les consignes du glossaire partagé pour la terminologie produit et le contexte du document pour cet usage précis. La Référence JSON détaille les indications contextuelles et les chemins protégés.

Exécuter la traduction en arrière-plan #

Enregistrez l’ID de la tâche renvoyé avant de la démarrer. Téléversez tous les éléments répertoriés dans uploads, puis appelez POST /v2/localization/jobs/:id/start. Même un document JSON intégré nécessite ce démarrage explicite.

Interrogez régulièrement la tâche depuis votre processus de traitement backend et téléchargez les résultats cibles terminés à l’aide des URL renvoyées. La requête d’enregistrement de la personne qui modifie le contenu peut recevoir une réponse dès que votre application a placé ce travail dans une file d’attente persistante. Elle n’a pas besoin de rester ouverte pendant la traduction ou la relecture humaine.

Pour les mises à jour incrémentales, conservez les artefacts sources précédents et les artefacts cibles acceptés, puis fournissez-les dans la requête de document suivante. La page Mises à jour des documents explique les limites de la réutilisation.

Enregistrer le travail après l’enregistrement de la source #

Une fois la transaction source validée, créez dans votre propre stockage un enregistrement de travail contenant l’ID du contenu, la révision source, la langue cible, l’enregistrement du moteur de localisation ou de sa configuration, ainsi que l’état du traitement. Mettez la traduction en file d’attente à partir de cet enregistrement. Cela évite qu’un processus de traitement traduise une modification que la transaction source annulerait ensuite.

Conservez un résultat par langue cible. L’allemand peut être prêt alors que le français nécessite une nouvelle tentative ou une relecture. Un unique indicateur global « traduit » masquerait cette différence à l’application qui décide quel contenu afficher. Les noms d’état que vous ajoutez relèvent de la conception de votre application, et non du vocabulaire des réponses de l’API.

Accepter les résultats uniquement pour la révision prévue #

Les modifications de la source et les traductions terminées peuvent arriver dans un ordre différent. Prenons cette séquence :

ÉvénementAction de l’application
La révision 12 est enregistréeMettre la révision 12 en file d’attente pour l’allemand.
La révision 13 est enregistrée avant la fin de ce travailMettre la révision 13 en file d’attente et la désigner comme source actuelle.
La traduction de la révision 13 se termineLa valider et l’accepter pour la révision 13.
La traduction de la révision 12 se termine plus tardConserver son résultat enregistré sans remplacer le texte accepté de la révision 13.

Au moment de l’activation, comparez la révision source de l’enregistrement de travail à la révision source actuelle. Dans votre système de stockage, effectuez cette comparaison et conditionnez l’écriture à cette révision, afin qu’aucune modification de la source ne puisse passer inaperçue entre les deux opérations. Si le travail correspondant à la révision actuelle n’a pas été mis en file d’attente ou a échoué, planifiez le traitement de cette révision plutôt que de réattribuer un ancien résultat.

Au moment de la lecture, demandez la traduction acceptée pour la langue et la révision souhaitées. Définissez le comportement de l’application si elle est absente : afficher le texte source, utiliser une langue de repli désignée, afficher une ancienne traduction explicitement suivie ou suspendre la publication. Le bon choix dépend des conséquences qu’un texte obsolète ou non traduit pourrait avoir pour la personne qui le lit. Une modification d’une condition du checkout peut justifier une politique plus stricte qu’une simple description de produit.

Reprendre le traitement avec l’identité distante et l’enregistrement local #

Enregistrez durablement la clé d’idempotence de la soumission avant de l’envoyer, puis son ID de tâche dès que la création renvoie une réponse. En cas de dépassement du délai d’attente réseau, répétez la requête de création à l’identique avec cette clé ou récupérez la tâche enregistrée. Répéter le démarrage agit sur la même tâche.

Après des échecs de lecture temporaires, reprenez les interrogations en espaçant progressivement les tentatives. L’expiration d’un délai côté client met fin à l’attente, pas au travail du serveur. Conservez séparément les résultats cibles terminés et les détails des cibles en échec ; une tâche en échec peut tout de même contenir des fichiers terminés utilisables.

Les erreurs d’authentification, les moteurs désactivés, les données d’entrée invalides et les limites du compte nécessitent une correction. Une tâche en attente peut être démarrée à nouveau une fois le blocage lié à une limite d’admission résolu. Pour un travail ayant échoué pendant l’exécution, corrigez la cause et soumettez les documents et les langues concernés avec une nouvelle clé d’idempotence.

Lors de l’acceptation, appliquez le même contrôle de révision à chaque résultat, y compris ceux récupérés après une reprise. Un téléchargement terminé confirme que le texte est disponible ; votre politique de validation et de relecture détermine s’il peut être publié.

Tester le cycle de vie de l’enregistrement #

Utilisez un enregistrement court contenant une variable, puis testez une mise à jour de la source, un échec pour une langue et des traductions qui se terminent dans le désordre. Vérifiez les clés des champs stockés et les identifiants des langues, ainsi que le texte. L’application ne doit afficher que la version acceptée par votre politique, et la personne chargée de la relecture doit pouvoir remonter à sa source.

Pour mesurer la qualité, conservez la paire source-cible avec le critère utilisé pour l’examiner. La conception des mesures s’applique indépendamment du workflow de génération. Votre enregistrement peut alors distinguer le texte renvoyé, une réponse de mesure, l’acceptation humaine et la publication, au lieu de les traiter comme un seul événement.