Créer des jobs de localisation

Créez un groupe de jobs de localisation : une seule requête pour diffuser votre contenu dans toutes les langues cibles de votre choix.

Vous avez une charge utile de chaînes et une liste de langues, et vous voulez tout traduire sans gérer vous-même la logique de fan-out. POST /jobs/localization prend la charge utile complète et jusqu’à 100 langues cibles dans une seule requête, puis renvoie 202 Accepted immédiatement avec un ID de groupe et un job par langue. Une seule requête, toutes les langues : la plateforme crée les jobs et traite chacun indépendamment.

POST /jobs/localization

Cette page couvre l’appel de création : ses paramètres, le format de la requête, la réponse 202, et la manière de rendre l’appel sûr à relancer. Vous découvrez la localisation asynchrone ? Commencez par la Vue d'ensemble de l’API de localisation asynchrone pour bien comprendre le modèle. Une fois le groupe créé, suivre un groupe de jobs vous explique ce que signifie le statut de chaque langue.

Paramètres#

sourceLocale, targetLocales et data sont obligatoires. Tout le reste permet d’ajuster le comportement ou de rendre l’appel plus sûr à répéter.

Requête#

Le champ data accepte des paires clé-valeur à plat ou des structures imbriquées avec objets et tableaux à n’importe quelle profondeur. Le moteur traduit chaque valeur de type chaîne, laisse intactes les valeurs non textuelles (nombres, booléens, null) et renvoie exactement la structure que vous avez envoyée. Vous pouvez donc lui transmettre le même objet que votre application stocke déjà, sans l’aplatir ni le remanier.

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "ja"],
  "data": {
    "lesson_title": "Introduction to Machine Learning",
    "lesson_summary": "This lesson covers the fundamentals of ML, including supervised and unsupervised learning."
  },
  "callbackUrl": "https://your-app.com/webhooks/translations",
  "idempotencyKey": "course_101-v3"
}

Cette charge utile imbriquée mélange du texte traduisible avec des valeurs qui doivent rester intactes : id, course_101, difficulty. Les chaînes sont traduites ; le reste est préservé selon son type. Quand vous devez aussi exclure une chaîne de la traduction (un slug, une URL de ressource, un code d’énumération), indiquez-la dans lockedKeys et elle sera réinjectée telle quelle dans la sortie de chaque langue.

Réponse (202 Accepted)#

L’appel renvoie immédiatement. Il n’attend pas la traduction : il vous donne l’ID du groupe et les IDs de job par langue, puis la plateforme traite chaque job indépendamment en arrière-plan.

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "pending",
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "queued" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "queued" },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued" }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

Trois langues demandées, trois jobs en retour, chacun au statut queued et prêt à s’exécuter. La signification de chaque statut au fil de l’avancement des jobs — et ce qui se passe quand une langue échoue pendant que les autres sont livrées — est expliquée dans Suivre un groupe de jobs.

Exemples#

La même requête en Node et en Python. Dans les deux cas, un seul POST suffit pour récupérer directement l’ID du groupe et le nombre de jobs dans la 202.

const response = await fetch("https://api.lingo.dev/jobs/localization", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LINGO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLocale: "en",
    targetLocales: ["de", "fr", "ja"],
    data: {
      title: "Introduction to Machine Learning",
      steps: [
        { heading: "What is ML?", body: "Machine learning is a subset of AI." },
        { heading: "Supervised Learning", body: "Training with labeled data." },
      ],
    },
    callbackUrl: "https://your-app.com/webhooks/translations",
  }),
});

const { groupId, jobs } = await response.json();
// 202 Accepted – the call returns without waiting for translation.
console.log(groupId);     // "ljg_A1b2C3d4E5f6G7h8"
console.log(jobs.length); // 3 – one queued job per target locale

Rendre l’appel sûr à relancer#

L’endroit naturel pour envoyer cette requête, c’est un hook de sauvegarde ou un gestionnaire d’événements — exactement le type de code qui s’exécute deux fois lorsqu’une nouvelle tentative se déclenche ou qu’un événement en double arrive. Sans protection, deux appels signifient deux groupes de jobs, et le même contenu est mis en file de traduction deux fois.

Transmettez un idempotencyKey et ce risque disparaît. Envoyez deux fois la même requête avec la même clé et la plateforme renvoie le groupe existant au lieu d’en créer un nouveau — sans deuxième série de jobs. Les clés sont portées par moteur ; la même clé utilisée avec un autre moteur correspond donc à un autre groupe.

const key = `${content.id}-v${content.version}`;

async function submit() {
  const response = await fetch("https://api.lingo.dev/jobs/localization", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sourceLocale: "en",
      targetLocales: ["de", "fr", "ja", "ko", "pt-BR"],
      data: { title: content.title, steps: content.steps },
      callbackUrl: "https://your-app.com/webhooks/translations",
      idempotencyKey: key,
    }),
  });
  return (await response.json()).groupId;
}

const first = await submit();
const again = await submit(); // same key – duplicate submission
console.log(first === again); // true – same group returned, no second set of jobs

C’est le POST unique qui diffuse une charge utile vers chaque langue, et vous pouvez l’envoyer sans risque depuis le même chemin de code que celui qui gère les nouvelles tentatives. Conservez le groupId : c’est ce que vous utiliserez ensuite pour le suivi et la progression en direct.

Étapes suivantes#