初めての翻訳リクエストを送信する

インラインJSONのジョブを作成・開始し、Node.jsでスペイン語の翻訳結果を保存します。

2つの英語メッセージをスペイン語に翻訳し、es.jsonとして保存します。必要なのは、Node.js 22以降、Lingo.devの組織、翻訳モデルが設定されたエンジン、そのエンジンで翻訳を実行する権限を持つAPIキーです。

最初のリクエストでは、人によるレビューなしで翻訳を実行するようにエンジンを設定します。送信からダウンロードまでの流れが正常に動作したら、レビューを追加できます。

リクエストを設定する #

ご自身の組織とエンジンのIDを使い、シェルで次の値を設定してください。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="welcome-messages-v1-es"

LINGO_REQUEST_IDは、この送信を識別する値です。同じリクエストを再試行するときは、同じ値を使ってください。原文、ロケール、その他のリクエストオプションを変更するときは、新しい値を指定してください。

作成・開始・ダウンロードを実行する #

次のプログラムをtranslate.mjsとして保存してください。

js
import { 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 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, 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;
}

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: ["es"],
      documents: [
        {
          key: "messages.json",
          format: { type: "json", options: { context: "Account settings buttons" } },
          source: { content: { save: "Save changes", cancel: "Cancel" } },
        },
      ],
    }),
  })
).json();

await writeFile("translation-job.json", JSON.stringify({ id: job.id, requestId }, null, 2));
console.log(`Created ${job.id}; saved its ID to translation-job.json`);
if (job.uploads.length !== 0) throw new Error("Upload the artifacts listed in job.uploads before starting");

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(`Still waiting for ${job.id}. Keep its ID and retrieve it again later.`);
  }
  await delay(2000);
  job = await (await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}`)).json();
}

const target = job.documents
  .find((document) => document.key === "messages.json")
  ?.targets.find((item) => item.locale === "es");
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();
await writeFile("es.json", JSON.stringify(translated, null, 2) + "\n");
console.log("Saved es.json");

プログラムを実行します。

sh
node translate.mjs

es.jsonを開き、saveとcancelを確認してください。どちらにもスペイン語のテキストが入っているはずです。APIは作成時にインラインJSONを保存しますが、別途/startリクエストを送信する必要があります。

中断したリクエストを再開する #

作成後にプログラムが停止した場合は、translation-job.jsonからIDを読み取り、ジョブを取得してください。同じIdempotency-Keyで同じ作成リクエストを再送信すると、元のジョブが取得されます。/startを再実行しても新しいジョブは作成されず、同じジョブの処理が続行されます。

ポーリングがタイムアウトすると、このプログラムの待機は終了しますが、サーバー側の処理はキャンセルされません。ジョブIDを保存し、後で再度確認してください。処理に失敗した翻訳先については、そのメッセージと各ステージの結果を確認してから、新しいキーで修正済みのリクエストを送信してください。

次は、ファイルの翻訳、JSONのヒントとキー制御の追加、またはアプリケーションへのライフサイクルの組み込みに進んでください。