Llama a la API desde JavaScript

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

Usa la función nativa fetch para traducir contenido estructurado desde tu servidor. Este ejemplo traduce del inglés al francés un encabezado de configuración de 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 una clave de API.

Configura la solicitud #

Crea una clave de API con acceso de traducción a tu motor y busca los ID 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 vuelvas a intentar 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 esto 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, luego abre settings.fr.json y revisa el encabezado en francés. El programa guarda el ID del trabajo antes de empezar y descarga el resultado solo cuando se completa la traducción al idioma de destino.

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

Continúa después de una interrupción #

Lee el ID de job.json y recupera el trabajo para seguir consultando 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, continúas con el mismo trabajo. Si se agota el tiempo de espera, el programa deja de esperar sin cancelar el trabajo en el servidor.

Para una aplicación que gestiona muchos envíos o espera una revisión humana, crea un flujo de trabajo de traducción que almacene los ID de los trabajos y las revisiones del contenido de origen, y recopile los resultados mediante un proceso de trabajo. Traducir archivos explica la carga de artefactos y los resultados parciales en varios idiomas.