Llama a la API desde JavaScript

Traduce JSON desde un servidor Node.js, espera el resultado y guárdalo en un archivo.

Usa fetch nativo para traducir contenido estructurado desde tu servidor. Este ejemplo traduce al francés un encabezado en inglés de los ajustes de la cuenta y lo guarda como settings.fr.json. Necesitas Node.js 22 o una versión posterior y un motor configurado con un modelo de traducción.

Mantén las credenciales en el servidor. El entorno de ejecución de React renderiza los catálogos sin necesidad de una clave de API.

Configura la solicitud #

Crea una clave de API con acceso de traducción a tu motor y busca los identificadores de la organización y del motor. Para este ejemplo, usa un motor con la revisión humana desactivada.

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"

Reutiliza LINGO_REQUEST_ID cuando reintentes este envío. Elige un valor nuevo si cambian el contenido de origen, los idiomas u otras opciones de la solicitud.

Traduce y guarda el resultado #

Guarda este código como 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");

Ejecuta node translate.mjs y, después, abre settings.fr.json y comprueba el encabezado en francés. El programa guarda el identificador del trabajo antes de empezar y solo descarga el resultado cuando finaliza la traducción al idioma de destino.

La función auxiliar de solicitudes comprueba el estado HTTP antes de leer una respuesta. Si se produce un error HTTP, usa el estado y los detalles del problema para decidir qué corregir. Puede producirse un error de red o agotarse el tiempo de espera después de que el servidor haya aceptado el trabajo.

Continúa tras una interrupción #

Lee el identificador de job.json y recupera el trabajo para seguir comprobando su estado. Si la respuesta de creación se perdió antes de guardar el archivo, repite la misma solicitud con la misma clave de idempotencia. Al repetir /start, se continúa con el mismo trabajo. Si se agota el tiempo de espera, el programa deja de esperar, pero el trabajo sigue ejecutándose en el servidor.

Si tu aplicación gestiona muchos envíos o espera una revisión humana, crea un flujo de trabajo de traducción que almacene los identificadores de los trabajos y las revisiones del contenido de origen, y recopile los resultados en un proceso de trabajo. Traducir archivos explica cómo subir artefactos y obtener resultados parciales en varios idiomas.