Automatizujte lokalizaci souborů pomocí API
Nahrajte zdrojový soubor, spusťte úlohu překladu dokumentu a stáhněte překlady do samostatného výstupního adresáře.
API pro dokumenty použijte, pokud soubory spravuje váš backend a potřebuje sladit překlad s vlastním úložištěm. Tento příklad přeloží messages/en.json do němčiny a francouzštiny. CLI provádí stejné operace se soubory v lokálním projektu.
Potřebujete Node.js 22 nebo novější, organizaci, engine s nakonfigurovaným modelem a klíč API s přístupem k překladu. Pro první spuštění nastavte překlad bez lidské kontroly; kontrolu přidejte, až bude fungovat celý cyklus zpracování souboru.
Připravte zdrojový soubor #
Vytvořte messages/en.json:
{
"title": "Account settings",
"save": "Save changes"
}Následujícím proměnným prostředí přiřaďte vlastní hodnoty:
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"Při opakování požadavků pro stejný zdroj a konfiguraci používejte stejné ID požadavku. Při odesílání nové revize ho změňte.
Nahrajte soubor, spusťte úlohu a stáhněte výsledky #
Uložte tento program jako 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`);
}Spusťte node translate-file.mjs a poté zkontrolujte translated/de.json a translated/fr.json. Oba soubory by měly zachovat klíče ze zdroje a obsahovat text v příslušném jazyce. Program ukládá výstupy odděleně od souborů aplikace, abyste je mohli zkontrolovat, než jimi nahradíte schválený obsah.
Obnovte zpracování bez vytvoření duplicitní úlohy #
file-job.json zaznamenává identifikátor vzdálené úlohy a hash zdroje. Pokud se ztratí odpověď na požadavek k nahrání nebo spuštění, načtěte danou úlohu, nahrajte zbývající artefakty a zopakujte požadavek na spuštění. I opakovaný požadavek na vytvoření s původním klíčem idempotence vrátí stejnou úlohu.
Vypršení časového limitu pro dotazování zpracování nezruší. Pokračujte v načítání zaznamenané úlohy; nevytvářejte novou jen proto, že lokální program přestal čekat.
Tento příklad se zastaví při prvním nedokončeném cílovém překladu nebo neúspěšném požadavku. Již uložené soubory zůstanou v translated/. Pokud chcete pokračovat, načtěte úlohu zaznamenanou v file-job.json a stáhněte její dokončené cílové překlady pomocí příslušných hodnot downloadUrl; viz stav úlohy a výsledky. Kvůli neúspěšnému stažení není nutné vytvářet novou překladovou úlohu.
Přidejte přírůstkové aktualizace #
Pro další revizi zadejte previousSource a previousTranslations spolu s novou adresou zdroje. Uchovejte bajtová data všech odkazovaných artefaktů, dokud se úspěšně nenahrají. Do předchozích cílových souborů, které předáte, zahrňte schválené ruční úpravy.
V části Překlad dokumentů najdete popis polí a pravidla pro opětovné použití. Před publikováním porovnejte zdrojovou revizi úlohy s aktuálním zdrojem a zkontrolujte, zda po odeslání nedošlo k úpravám cílových překladů. Tento krok schvalování vysvětluje část Vytvoření překladového workflow.