APIでファイルのローカライズを自動化する

ソースファイルをアップロードし、ドキュメントジョブを開始して、翻訳結果を別の出力ディレクトリにダウンロードします。

バックエンドでファイルを管理し、独自のストレージと翻訳処理を連携させる場合は、ドキュメントAPIを使用します。この例では、messages/en.jsonをドイツ語とフランス語に翻訳します。ローカルプロジェクトでは、CLIで同じファイル操作を実行できます。

Node.js 22以降、組織、モデルを設定したエンジン、翻訳へのアクセス権があるAPIキーが必要です。初回は人によるレビューなしで翻訳するように設定してください。ファイルの一連の処理が正常に動作することを確認してから、レビューを追加します。

ソースファイルを準備する #

messages/en.jsonを作成します。

json
{
  "title": "Account settings",
  "save": "Save changes"
}

次の環境変数に、ご自身の環境に合わせた値を設定します。

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="account-settings-v1-de-fr"

同じソースと設定で再試行する場合は、同じリクエストIDを使用してください。新しいリビジョンを送信する際は、リクエストIDを変更してください。

アップロード、開始、結果の取得 #

このプログラムをtranslate-file.mjsとして保存します。

js
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`);
}

node translate-file.mjsを実行し、translated/de.jsonとtranslated/fr.jsonを確認します。どちらもソースのキーが保持され、それぞれの言語に翻訳されていることを確認してください。このプログラムは出力をアプリケーションファイルとは別に保存するため、採用済みのコンテンツを置き換える前にレビューできます。

ジョブを重複させずに復旧する #

file-job.jsonには、リモート側の識別情報とソースのハッシュが記録されます。アップロードまたは開始リクエストへの応答が失われた場合は、そのジョブを取得し、残りの成果物をアップロードして、開始リクエストを再送してください。元の冪等性キーを使って作成リクエストを再送した場合も、同じジョブが返されます。

ポーリングがタイムアウトしても、処理はキャンセルされません。記録済みのジョブを引き続き取得してください。ローカルプログラムが待機を終了したという理由だけで、別のジョブを作成しないでください。

この例では、未完了の翻訳先またはリクエストの失敗を最初に検出した時点で処理を停止します。保存済みのファイルはtranslated/に残ります。続行するには、file-job.jsonに記録されたジョブを取得し、完了した翻訳先のdownloadUrlの値を使って翻訳結果をダウンロードしてください。詳しくはジョブのステータスと結果を参照してください。ダウンロードに失敗しても、新しい翻訳ジョブを作成する必要はありません。

差分更新を追加する #

次のリビジョンでは、新しいソースのアドレスとともにpreviousSourceとpreviousTranslationsを指定してください。参照するすべての成果物のバイトデータは、アップロードが成功するまで保持してください。前回の翻訳先ファイルを指定する際は、人による編集のうち採用済みの内容を反映させてください。

ドキュメントを翻訳するでは、フィールドと再利用のルールを説明しています。公開前に、ジョブのソースリビジョンを現在のソースと比較し、送信後に翻訳先が編集されていないか確認してください。翻訳結果を採用する際の手順は、翻訳ワークフローを構築するで説明しています。