通过 JavaScript 调用 API
在 Node.js 服务器上翻译 JSON,等待结果并保存到文件。
使用原生 fetch 在服务器上翻译结构化内容。本示例将英文的账户设置标题翻译成法语,并保存为 settings.fr.json。你需要 Node.js 22 或更高版本,以及一个已配置翻译模型的引擎。
请将凭据留在服务器端。React 运行时无需 API 密钥即可渲染翻译目录。
配置请求 #
创建一个具有引擎翻译权限的 API 密钥,并查找组织和引擎的 ID。本示例需使用已禁用人工审核的引擎。
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="settings-v1-fr"重试本次提交时,请复用 LINGO_REQUEST_ID。如果源内容、语言区域或其他请求选项发生变化,请使用新值。
翻译并保存结果 #
将以下内容保存为 translate.mjs:
js
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");运行 node translate.mjs,然后打开 settings.fr.json,查看法语标题。程序会在开始处理前保存任务 ID,且仅在目标完成后下载结果。
请求辅助函数会先检查 HTTP 状态,再读取响应。如果出现 HTTP 错误,请根据状态和问题详情判断需要修正哪些内容。即使服务器已接受任务,也可能发生网络错误或超时。
中断后继续 #
从 job.json 中读取 ID,并获取任务,继续检查其状态。如果创建请求的响应在文件保存前丢失,请使用相同的幂等键重新发送同一请求。再次执行 /start 会继续处理同一个任务。超时会结束程序的等待,但不会取消服务器端的任务。
如果应用需要处理大量提交或等待人工审核,请构建翻译工作流,保存任务 ID 和源内容版本,并通过工作进程收集结果。翻译文件介绍了产物上传,以及多种语言的部分结果处理。