Votre contenu évolue, et il doit désormais atteindre chaque langue dans laquelle vous publiez. Un module de formation reçoit une nouvelle leçon. Une entrée CMS est enregistrée. Une description produit est modifiée. La traduction doit partir en allemand, en français, en japonais et dans une douzaine d’autres langues – sans que votre application se retrouve bloquée pendant ce temps.
L’API de localisation asynchrone est conçue précisément pour ce moment : une requête, toutes les langues, des résultats dès qu’ils arrivent. Vous envoyez votre contenu une seule fois avec les langues cibles, récupérez immédiatement un 202, et la plateforme traduit chaque langue dans un job d’arrière-plan indépendant. Vous conservez votre glossaire, votre voix de marque et votre configuration de modèle – le même moteur que l’API synchrone utilise – et vous n’avez plus à gérer les relances.
Sur cette page
Le problème#
Les plateformes de formation, les systèmes de gestion de contenu et les outils d’e-learning doivent souvent traduire du contenu dans des dizaines de langues dès sa création ou sa mise à jour. L’API de localisation synchrone fonctionne, mais elle impose un compromis à grande échelle.
Prenons un module de formation rédigé en anglais qui doit être diffusé à des apprenants dans 14 langues. Avec l’API synchrone, vous avez deux options, et les deux ont un coût :
Lancer 14 appels en parallèle – une requête par langue cible, chacune transportant la même payload source. Vous pouvez afficher chaque langue dès qu’elle revient, mais vous gérez 14 allers-retours réseau avec des données redondantes, et la logique de relance vous incombe dès que l’un d’eux échoue.
Traduire les 14 dans un seul appel synchrone – moins d’allers-retours, mais vous devez alors attendre la langue la plus lente avant de pouvoir en afficher une seule.
Dans les deux cas, votre application reste mobilisée pendant le traitement des traductions. Si votre serveur redémarre en cours de route, les traductions en cours sont perdues. Si une langue échoue, la gestion des échecs partiels vous revient. Et aucune de ces approches n’envoie à vos utilisateurs un signal clair indiquant que les traductions sont en cours.
L’API asynchrone supprime ce compromis. Une seule requête crée un groupe de jobs avec un job par langue cible. Chaque job s’exécute indépendamment via votre moteur de localisation dans un workflow d’arrière-plan durable – ainsi, un redémarrage de votre serveur ne vous fait rien perdre, puisque le traitement ne s’exécute pas dans votre processus. Les résultats sont livrés langue par langue dès qu’ils sont prêts. Votre application reste réactive. Les échecs restent isolés. La plateforme gère les relances et la livraison.
Une seule langue, et vous pouvez attendre une seconde ? Optez pour le synchrone.
L’API asynchrone prend tout son sens lorsque vous avez beaucoup de langues, un contenu long ou une interface qui doit afficher la progression. Si vous avez besoin d’une seule paire de langues et pouvez attendre un seul aller-retour, le point de terminaison Localize synchrone est l’option la plus simple – une requête, les données traduites reviennent dans la réponse, sans endpoint webhook à maintenir. Optez pour l’asynchrone lorsque le job est trop volumineux, trop lent ou implique trop de langues pour bloquer dessus.
Fonctionnement#
Trois étapes, et seule la première se produit dans votre cycle requête/réponse. Les deux autres se déroulent sur la plateforme, à leur propre rythme.
Envoyer une requête
Envoyez votre contenu et les langues cibles par POST à /jobs/localization. L’API valide la payload, crée un groupe de jobs avec un job par langue, et renvoie un 202 avec l’ID du groupe et un récapitulatif des jobs. Votre application peut continuer immédiatement – rien n’est traduit dans cet appel. Consultez Créer des jobs pour voir la structure complète de la requête et de la réponse.
La plateforme traite chaque langue indépendamment
Chaque job s’exécute via votre moteur de localisation dans un workflow d’arrière-plan durable, en appliquant la même sélection de modèle, le même glossaire, la même voix de marque et les mêmes instructions que l’API synchrone. Chaque job peut aussi passer par un pipeline d’étapes de pré-édition, de relecture humaine, de post-édition, de reformulation et de retraduction. Un job passe de queued à processing puis à un état terminal : completed, completed_with_warnings ou failed – et le résultat d’une langue ne bloque jamais celui d’une autre.
Recevoir les résultats à mesure qu’ils arrivent
Dès qu’une langue est prête, la plateforme livre son résultat à votre URL de webhook. Pour afficher la progression en direct dans votre interface – un compteur « 3 sur 14 prêts » qui se met à jour à mesure que les jobs se terminent – connectez-vous au WebSocket du groupe. Si vous préférez interroger l’état, vous pouvez sonder le groupe à intervalles réguliers.
Authentification
Chaque requête – REST comme WebSocket – s’authentifie avec votre en-tête X-API-Key. Les clés sont limitées à l’organisation et donnent accès à chaque moteur de l’organisation. Voir Authentification pour les détails, et Clés API pour en créer une.
Le modèle de groupe de jobs#
Chaque soumission produit un groupe qui contient un job par langue cible. C’est tout le modèle mental – et c’est ce qui permet de répondre aux questions les plus délicates.
Un lecteur sceptique déroule déjà la liste : que se passe-t-il si une langue échoue, et qu’advient-il de mon application pendant que tout cela est en cours ? Le modèle de groupe répond aux deux.
- Les échecs restent isolés, parce que chaque langue a son propre job. Si l’allemand réussit et que le japonais échoue, la traduction allemande est livrée normalement et le job japonais porte son propre
errorMessage. Le groupe signalepartial, et le travail déjà réussi est quand même livré. Un échec sur une langue ne peut pas annuler une autre déjà terminée. Toute la sémantique des statuts est détaillée dans Suivre un groupe de jobs. - Le travail en cours survit à un redémarrage, car il ne s’exécute pas dans votre processus. Chaque job est un workflow d’arrière-plan durable sur la plateforme. Si votre serveur redémarre, rien de ce qui est en cours n’est perdu – vous vous reconnectez ou vous sondez, et le groupe est exactement là où vous l’aviez laissé.
- Le groupe offre un modèle de progression que vous pouvez brancher à une interface. Stockez le
groupIddu202, puis alimentez un indicateur de progression à partir des livraisons webhook ou des instantanés WebSocket. « 3 langues sur 14 prêtes » n’est qu’un compteur basé sur les jobs enfants du groupe.
Le coût réel de ce modèle est simple : vous prenez en charge une petite intégration dont l’appel synchrone vous dispense. Pour recevoir les résultats, vous devez exposer un endpoint webhook HTTPS, ou maintenir un WebSocket côté serveur, et traiter chaque langue à son arrivée au lieu de lire directement les données traduites dans une seule réponse. En échange, la plateforme gère les relances, l’isolation des échecs et la livraison – et votre application n’est jamais bloquée par une traduction.
C’est exactement le compromis pour lequel l’API asynchrone a été conçue : une requête, toutes les langues, des résultats dès qu’ils arrivent. Les pages suivantes en déclinent les verbes.
