Tâches de traduction

Créez et démarrez des tâches regroupant un ou plusieurs documents et une ou plusieurs langues cibles.

Une tâche traduit des documents via un seul moteur de localisation. Chaque document possède une clé stable et une cible par langue demandée. Utilisez du JSON intégré pour le contenu en mémoire ou des adresses d’artefacts pour les fichiers.

Toutes les routes ci-dessous utilisent https://api.lingo.dev et l’authentification de l’API.

Créer une tâche #

http
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr
json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "order-confirmation.json",
      "format": { "type": "json" },
      "source": { "content": { "subject": "Your order is confirmed" } }
    }
  ]
}

Champs de la requête #

ChampObligatoireDescription
engineIdOuiMoteur de l’organisation que l’appelant peut utiliser pour traduire.
sourceLocaleOuiLangue source.
targetLocalesOuiTableau non vide de langues cibles sans doublons. Un document ne peut pas avoir sa langue source comme langue cible.
documentsOuiTableau non vide de documents dont les valeurs key sont uniques.
originIdNonIdentifiant non vide de 512 caractères maximum indiquant l’emplacement des documents, par exemple github:acme/web. Il permet de rattacher les modifications ultérieures issues de cette origine aux mesures de traduction.

Chaque document comporte les champs suivants :

ChampObligatoireDescription
keyOuiChemin logique ou nom de fichier non vide, unique au sein de cette tâche. Gardez la même valeur d’une révision à l’autre.
formatOuiObjet décrivant le format, avec un type et un options propre au format.
sourceOuiAdresse d’artefact SHA-256, ou { "content": { ... } } pour du JSON intégré.
previousSourceNonAdresse de l’artefact source précédent. Omettez ce champ ou utilisez null pour une première traduction.
previousTranslationsNonTableau de { "locale": "de", "artifact": "SHA256" }. La valeur par défaut est [] ; chaque langue doit être unique et figurer parmi les langues cibles de ce document.
targetLocalesNonListe non vide de langues sans doublons remplaçant les langues cibles pour ce document. Si ce champ est omis ou vaut null, les langues cibles de la tâche sont utilisées.

Lorsque vous utilisez keyScope ou termScope, fournissez une traduction précédente pour chaque cible. Consultez les formats de documents et les mises à jour.

Idempotence #

Envoyez un Idempotency-Key non vide de 255 caractères maximum. La portée des clés est limitée au moteur ; le préfixe content-sync: est réservé. Conservez la clé avec la requête d’origine et renvoyez cette requête à l’identique si la réponse à la création est incertaine.

La réutilisation d’une clé renvoie la tâche initialement créée avec cette clé, sans mettre à jour ses documents ni ses langues. Utilisez une nouvelle clé si le travail a changé. Une option d’exécution incompatible peut entraîner LocalizationJobIdempotencyKeyReused (422).

Réponse à la création #

Une création réussie renvoie le statut HTTP 200 et la réponse de la tâche, généralement avec status: { "_tag": "Pending" }. Enregistrez durablement id avant de continuer. Le tableau uploads répertorie les artefacts d’entrée manquants sous la forme { "address": "...", "uploadUrl": "..." }.

La création enregistre les sources intégrées. Elle ne démarre pas la traduction, même lorsque uploads est vide.

Téléverser et démarrer #

Téléversez chaque artefact manquant vers son uploadUrl à l’aide d’un PUT authentifié contenant les octets d’origine. Appelez ensuite :

http
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY

La requête de démarrage ne contient aucun corps. Sa réponse HTTP 200 contient l’enregistrement actuel de la tâche. Répéter le démarrage pour une même tâche est sans risque et permet de reprendre un lancement dont l’issue est incertaine ; cela ne crée pas de nouvelle tâche et ne relance pas une tâche terminée.

Le démarrage vérifie les artefacts téléversés, la configuration du moteur et les limites du compte. ArtifactsNotUploaded (409) répertorie les entrées manquantes. Si la limite quotidienne de jetons est atteinte (429) ou si les crédits sont insuffisants, la tâche reste en attente ; corrigez le problème avant de la démarrer à nouveau. Consultez les erreurs.

Configurer les étapes du pipeline #

Configurez le pipeline du moteur avant le démarrage. Sa configuration est enregistrée au démarrage. Les étapes retenues pour les cibles de la tâche indiquent le travail effectivement sélectionné, compte tenu des fonctionnalités disponibles dans l’offre.

Récupérer les résultats et reprendre après un échec #

Récupérez la tâche pour examiner chaque cible et télécharger les fichiers terminés. Utilisez la progression des étapes pour distinguer le travail des modèles, les attentes de relecture, le travail ignoré et les échecs.

Une tâche ayant échoué peut tout de même contenir des cibles terminées. Conservez ces résultats puis, après avoir corrigé la cause de l’échec, soumettez uniquement le travail à régénérer avec une nouvelle clé d’idempotence. Conservez les révisions sources avec les identifiants des tâches afin qu’une livraison ultérieure n’écrase pas des traductions plus récentes.

Listez les tâches pour retrouver les soumissions par moteur, état, déclencheur ou clé de service.