JavaScriptからAPIを呼び出す
Node.jsサーバーからJSONを翻訳し、完了を待って結果をファイルに保存します。
標準のfetchを使って、サーバーから構造化コンテンツを翻訳します。この例では、英語のアカウント設定の見出しをフランス語に翻訳し、settings.fr.jsonとして保存します。Node.js 22以降と、翻訳モデルが設定されたエンジンが必要です。
認証情報はサーバー側で管理してください。Reactランタイムは、APIキーを使わずにカタログを描画します。
リクエストを設定する #
エンジンで翻訳を実行する権限を持つAPIキーを作成し、組織とエンジンのIDを確認してください。この例では、人によるレビューが無効になっているエンジンを使用します。
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として保存します。
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とソースのリビジョンを保存し、ワーカーで結果を収集する翻訳ワークフローを構築してください。ファイルを翻訳するでは、成果物のアップロードと、複数言語にわたる部分的な結果について説明しています。