Как вызвать API из JavaScript

Переведите JSON с сервера Node.js, дождитесь результата и сохраните его в файл.

Используйте встроенный fetch, чтобы переводить структурированный контент с сервера. В этом примере заголовок настроек учётной записи переводится с английского на французский и сохраняется в settings.fr.json. Вам понадобятся Node.js 22 или новее и движок с настроенной моделью перевода.

Храните учётные данные на сервере. Среда выполнения React показывает каталоги без ключа API.

Настройте запрос #

Создайте ключ API с доступом к переводу через ваш движок и найдите ИД организации и движка. Для этого примера используйте движок с отключённой ручной проверкой.

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 и проверьте заголовок на французском. Программа сохраняет ИД задания до начала работы и скачивает результат только после завершения перевода для целевой локали.

Вспомогательная функция для запросов проверяет статус HTTP перед чтением ответа. При ошибке HTTP используйте статус и сведения о проблеме, чтобы понять, что нужно исправить. Ошибка сети или тайм-аут могут возникнуть уже после того, как сервер принял задание.

Продолжите работу после прерывания #

Прочитайте ИД из job.json и получите задание, чтобы продолжить проверять его состояние. Если ответ на запрос создания потерялся до сохранения файла, повторите тот же запрос с тем же ключом идемпотентности. Повторный вызов /start продолжает работу с тем же заданием. При тайм-ауте программа перестаёт ждать, но работа на сервере не отменяется.

Если приложение обрабатывает много запросов или ждёт ручной проверки, создайте рабочий процесс перевода, который хранит ИД заданий и версии исходного контента, а результаты собирает в обработчике. В разделе «Как переводить файлы» описаны загрузка артефактов и частичные результаты для нескольких языков.