Effectuez votre première demande de traduction

Créez une tâche avec du JSON intégré, lancez-la et enregistrez le résultat en espagnol avec Node.js.

Traduisez deux messages de l’anglais vers l’espagnol et enregistrez-les dans es.json. Vous avez besoin de Node.js 22 ou d’une version ultérieure, d’une organisation Lingo.dev, d’un moteur configuré avec un modèle de traduction et d’une clé API autorisant la traduction avec ce moteur.

Pour cette première demande, configurez le moteur pour traduire sans relecture humaine. Vous pourrez ajouter une étape de relecture une fois le processus de soumission et de téléchargement opérationnel.

Configurez la demande #

Définissez ces valeurs dans votre terminal avec les identifiants de votre organisation et de votre moteur. La page Sélectionner l’organisation et le moteur explique comment les trouver.

sh
export LINGO_API_KEY="YOUR_API_KEY"
export LINGO_ORGANIZATION_ID="YOUR_ORGANIZATION_ID"
export LINGO_ENGINE_ID="YOUR_ENGINE_ID"
export LINGO_REQUEST_ID="welcome-messages-v1-es"

LINGO_REQUEST_ID identifie cette soumission. Réutilisez cette valeur si vous relancez la même demande. Choisissez une nouvelle valeur si la source, les langues ou d’autres options de la demande changent.

Créez, lancez et téléchargez #

Enregistrez ce programme sous le nom translate.mjs :

js
import { writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";

const origin = "https://api.lingo.dev";
const {
  LINGO_API_KEY: apiKey,
  LINGO_ORGANIZATION_ID: orgId,
  LINGO_ENGINE_ID: engineId,
  LINGO_REQUEST_ID: requestId,
} = process.env;
if (!apiKey || !orgId || !engineId || !requestId) {
  throw new Error("Set LINGO_API_KEY, LINGO_ORGANIZATION_ID, LINGO_ENGINE_ID, and LINGO_REQUEST_ID");
}

async function request(path, options = {}) {
  const response = await fetch(new URL(path, origin), {
    ...options,
    headers: { "X-API-Key": apiKey, ...options.headers },
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return response;
}

let job = await (
  await request(`/v2/organizations/${encodeURIComponent(orgId)}/localization/jobs`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "Idempotency-Key": requestId },
    body: JSON.stringify({
      engineId,
      sourceLocale: "en",
      targetLocales: ["es"],
      documents: [
        {
          key: "messages.json",
          format: { type: "json", options: { context: "Account settings buttons" } },
          source: { content: { save: "Save changes", cancel: "Cancel" } },
        },
      ],
    }),
  })
).json();

await writeFile("translation-job.json", JSON.stringify({ id: job.id, requestId }, null, 2));
console.log(`Created ${job.id}; saved its ID to translation-job.json`);
if (job.uploads.length !== 0) throw new Error("Upload the artifacts listed in job.uploads before starting");

job = await (
  await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}/start`, {
    method: "POST",
  })
).json();

const deadline = Date.now() + 120_000;
while (["Pending", "Running"].includes(job.status._tag)) {
  if (Date.now() >= deadline) {
    throw new Error(`Still waiting for ${job.id}. Keep its ID and retrieve it again later.`);
  }
  await delay(2000);
  job = await (await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}`)).json();
}

const target = job.documents
  .find((document) => document.key === "messages.json")
  ?.targets.find((item) => item.locale === "es");
if (target?.status._tag !== "Completed") {
  throw new Error(`Translation did not complete: ${JSON.stringify(job.status)}`);
}
const translated = await (await request(target.status.downloadUrl)).json();
await writeFile("es.json", JSON.stringify(translated, null, 2) + "\n");
console.log("Saved es.json");

Exécutez-le :

sh
node translate.mjs

Ouvrez es.json et examinez save et cancel. Les deux doivent contenir du texte en espagnol. L’API stocke le JSON intégré lors de la création, mais une requête /start séparée reste nécessaire.

Reprenez une demande interrompue #

Si le programme s’arrête après la création, relevez l’identifiant dans translation-job.json et récupérez la tâche. En répétant la même demande de création avec la même valeur Idempotency-Key, vous récupérez la tâche d’origine. En répétant /start, vous poursuivez la même tâche au lieu d’en créer une autre.

Lorsque le délai d’interrogation expire, le programme cesse d’attendre, mais le serveur poursuit son travail. Conservez l’identifiant de la tâche et vérifiez à nouveau plus tard. En cas d’échec pour une cible, examinez son message et les résultats de ses étapes avant de soumettre une demande corrigée avec une nouvelle clé.

Ensuite, traduisez des fichiers, ajoutez des indications JSON et des contrôles sur les clés ou intégrez le cycle de vie à votre application.