Make your first translation request

Create an inline JSON job, start it, and save the Spanish result with Node.js.

Translate two English messages into Spanish and save them as es.json. You need Node.js 22 or later, a Lingo.dev organization, an engine configured with a translation model, and an API key with translation access to that engine.

For this first request, configure the engine to run translation without human review. You can add review after the submission and download flow works.

Set the request configuration #

Set these values in your shell, using your own organization and engine IDs. Select the organization and engine explains how to find them.

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 identifies this submission. Reuse it when retrying the same request. Choose a new value when the source, locales, or other request options change.

Create, start, and download #

Save this program as 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");

Run it:

sh
node translate.mjs

Open es.json and inspect save and cancel. Both should contain Spanish text. The API stores inline JSON during creation, but the separate /start request is still required.

Recover an interrupted request #

If the program stops after creation, read the ID from translation-job.json and retrieve the job. Repeating the same create request with the same Idempotency-Key retrieves the original job. Repeating /start continues the same job rather than creating another one.

A polling timeout ends this program's wait; it does not cancel the server's work. Keep the job ID and check again later. For a failed target, inspect its message and stage results before submitting a corrected request with a new key.

Next, translate files, add JSON hints and key controls, or integrate the lifecycle into your application.