Appeler l’API depuis JavaScript
Traduisez du JSON depuis un serveur Node.js, attendez le résultat et enregistrez-le dans un fichier.
Utilisez la fonction native fetch pour traduire du contenu structuré depuis votre serveur. Cet exemple traduit en français un titre des paramètres du compte rédigé en anglais et l’enregistre sous settings.fr.json. Vous avez besoin de Node.js 22 ou d’une version ultérieure et d’un moteur configuré avec un modèle de traduction.
Gardez les identifiants sur le serveur. L’environnement d’exécution React affiche les catalogues sans clé API.
Configurer la requête #
Créez une clé API autorisant la traduction avec votre moteur et récupérez les identifiants de l’organisation et du moteur. Pour cet exemple, utilisez un moteur dont la relecture humaine est désactivée.
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="settings-v1-fr"Réutilisez LINGO_REQUEST_ID lorsque vous retentez cet envoi. Choisissez une nouvelle valeur si la source, les langues ou d’autres options de la requête changent.
Traduire et enregistrer le résultat #
Enregistrez ce code sous translate.mjs :
import { writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";
const apiKey = process.env.LINGO_API_KEY;
const orgId = process.env.LINGO_ORGANIZATION_ID;
const engineId = process.env.LINGO_ENGINE_ID;
const requestId = process.env.LINGO_REQUEST_ID;
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, "https://api.lingo.dev"), {
...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: ["fr"],
documents: [
{
key: "settings.json",
format: { type: "json" },
source: { content: { heading: "Account settings" } },
},
],
}),
})
).json();
await writeFile("job.json", JSON.stringify({ id: job.id, requestId }, null, 2));
if (job.uploads.length) throw new Error("Upload the missing artifacts before starting");
const jobPath = `/v2/localization/jobs/${encodeURIComponent(job.id)}`;
job = await (await request(`${jobPath}/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 job.json and check again later`);
await delay(2000);
job = await (await request(jobPath)).json();
}
const target = job.documents
.find((document) => document.key === "settings.json")
?.targets.find((item) => item.locale === "fr");
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();
if (typeof translated.heading !== "string") throw new Error("The result is missing its heading");
await writeFile("settings.fr.json", JSON.stringify(translated, null, 2) + "\n");
console.log("Saved settings.fr.json");Exécutez node translate.mjs, puis ouvrez settings.fr.json et examinez le titre en français. Le programme enregistre l’identifiant de la tâche avant de lancer le traitement et ne télécharge le résultat qu’une fois le traitement de la cible terminé.
La fonction utilitaire de requête vérifie le statut HTTP avant de lire la réponse. En cas d’erreur HTTP, appuyez-vous sur le statut et les détails du problème pour déterminer ce qu’il faut corriger. Une erreur réseau ou un dépassement du délai d’attente peut survenir après que le serveur a accepté la tâche.
Reprendre après une interruption #
Lisez l’identifiant dans job.json et récupérez la tâche pour continuer à suivre son état. Si la réponse à la requête de création a été perdue avant l’enregistrement du fichier, renvoyez la même requête avec la même clé d’idempotence. Répéter /start permet de poursuivre la même tâche. Un dépassement du délai d’attente met fin à l’attente du programme sans annuler le traitement sur le serveur.
Pour une application qui gère de nombreux envois ou attend une relecture humaine, créez un workflow de traduction qui stocke les identifiants des tâches et les révisions de la source, et collecte les résultats dans un processus de traitement en arrière-plan. Traduire des fichiers présente l’envoi d’artefacts et les résultats partiels dans plusieurs langues.