Automatiser la localisation de fichiers avec l’API
Importez un fichier source, lancez une tâche de traduction de document et téléchargez les traductions dans un répertoire de sortie distinct.
Utilisez l’API de documents lorsque votre backend gère les fichiers et doit coordonner la traduction avec son propre système de stockage. Cet exemple traduit messages/en.json en allemand et en français. La CLI effectue les mêmes opérations sur les fichiers d’un projet local.
Vous avez besoin de Node.js 22 ou d’une version ultérieure, d’une organisation, d’un moteur configuré avec un modèle et d’une clé API donnant accès à la traduction. Pour cette première exécution, configurez la traduction sans relecture humaine ; ajoutez la relecture une fois le cycle de vie des fichiers opérationnel.
Préparer un fichier source #
Créez messages/en.json :
{
"title": "Account settings",
"save": "Save changes"
}Définissez les variables d’environnement suivantes avec vos propres valeurs :
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="account-settings-v1-de-fr"Conservez le même identifiant de requête lorsque vous réessayez avec cette source et cette configuration. Changez-le lorsque vous soumettez une nouvelle révision.
Importer, lancer et récupérer #
Enregistrez ce programme sous le nom translate-file.mjs :
import { createHash } from "node:crypto";
import { mkdir, readFile, 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 the four LINGO environment variables");
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;
}
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");
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: ["de", "fr"],
documents: [{ key: "messages/en.json", format: { type: "json" }, source: address }],
}),
})
).json();
await writeFile("file-job.json", JSON.stringify({ id: job.id, requestId, source: address }, null, 2));
for (const upload of job.uploads) {
await request(upload.uploadUrl, {
method: "PUT",
headers: { "Content-Type": "application/octet-stream" },
body: bytes,
});
}
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(`Keep job ${job.id} and check again later`);
await delay(2000);
job = await (await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}`)).json();
}
await mkdir("translated", { recursive: true });
for (const { locale, status } of job.documents[0].targets) {
if (status._tag !== "Completed") {
throw new Error(`Inspect job ${job.id}: ${locale} is ${status._tag}`);
}
const output = await request(status.downloadUrl);
await writeFile(`translated/${locale}.json`, new Uint8Array(await output.arrayBuffer()));
console.log(`Saved translated/${locale}.json`);
}Exécutez node translate-file.mjs, puis examinez translated/de.json et translated/fr.json. Les deux fichiers doivent conserver les clés du fichier source et contenir le texte dans la langue correspondante. Le programme garde les fichiers de sortie à part des fichiers de l’application pour vous permettre de les relire avant de remplacer le contenu accepté.
Reprendre sans dupliquer la tâche #
file-job.json enregistre l’identifiant distant et l’empreinte de la source. Si la réponse à une requête d’importation ou de lancement est perdue, récupérez cette tâche, importez les artefacts restants et renvoyez la requête de lancement. Répéter la requête de création avec la clé d’idempotence d’origine renvoie également la même tâche.
L’expiration du délai d’interrogation n’annule pas le traitement. Continuez à consulter la tâche enregistrée ; n’en créez pas une autre simplement parce que le programme local a cessé d’attendre.
Cet exemple s’arrête à la première cible incomplète ou à la première requête qui échoue. Les fichiers déjà enregistrés restent dans translated/. Pour reprendre, récupérez la tâche enregistrée dans file-job.json et téléchargez ses cibles terminées à l’aide de leurs valeurs downloadUrl ; consultez l’état et les résultats des tâches. Un échec de téléchargement ne nécessite pas de nouvelle tâche de traduction.
Ajouter des mises à jour incrémentales #
Pour la prochaine révision, fournissez previousSource et previousTranslations avec la nouvelle adresse du fichier source. Conservez les octets de chaque artefact référencé jusqu’à ce que l’importation réussisse. Intégrez les modifications humaines acceptées aux fichiers cibles de la révision précédente que vous fournissez.
Traduire des documents détaille les champs et les règles de réutilisation. Avant de publier, comparez la révision source de la tâche avec votre source actuelle et vérifiez si les cibles ont été modifiées après la soumission. Créer un workflow de traduction explique cette étape d’acceptation.