Automatiza la localización de archivos con la API

Sube un archivo de origen, inicia un trabajo de traducción de documentos y descarga las traducciones en un directorio de salida independiente.

Usa la API de documentos cuando tu backend gestione los archivos y necesite coordinar la traducción con su propio almacenamiento. Este ejemplo traduce messages/en.json al alemán y al francés. La CLI realiza las mismas operaciones con archivos en un proyecto local.

Necesitas Node.js 22 o una versión posterior, una organización, un motor configurado con un modelo y una clave de API con acceso a la traducción. Para esta primera ejecución, configura la traducción sin revisión humana; añade la revisión cuando el ciclo de vida de los archivos funcione correctamente.

Prepara un archivo de origen #

Crea messages/en.json:

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

Configura las siguientes variables de entorno con tus propios valores:

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"

Usa el mismo ID de solicitud al reintentar con este archivo de origen y esta configuración. Cámbialo cuando envíes una nueva revisión.

Sube, inicia y recoge los resultados #

Guarda este programa como 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`);
}

Ejecuta node translate-file.mjs y después comprueba translated/de.json y translated/fr.json. Ambos deben conservar las claves del archivo de origen y contener el texto en el idioma correspondiente. El programa mantiene los archivos de salida separados de los archivos de la aplicación para que puedas revisarlos antes de sustituir el contenido aceptado.

Reanuda el proceso sin duplicar el trabajo #

file-job.json registra el identificador remoto y el hash del archivo de origen. Si se pierde la respuesta de una subida o de una solicitud de inicio, recupera ese trabajo, sube los artefactos que falten y repite la solicitud de inicio. Si repites la creación con la clave de idempotencia original, también obtendrás el mismo trabajo.

Que se agote el tiempo de espera de la consulta periódica no cancela el trabajo. Sigue consultando el trabajo registrado; no crees otro solo porque el programa local haya dejado de esperar.

Este ejemplo se detiene en cuanto encuentra un destino incompleto o falla una solicitud. Los archivos ya guardados permanecen en translated/. Para continuar, recupera el trabajo registrado en file-job.json y descarga los destinos completados con sus valores de downloadUrl; consulta el estado y los resultados del trabajo. Si falla una descarga, no necesitas crear un nuevo trabajo de traducción.

Añade actualizaciones incrementales #

Para la siguiente revisión, proporciona previousSource y previousTranslations junto con la nueva dirección del archivo de origen. Conserva los bytes de cada artefacto referenciado hasta que la subida se complete correctamente. Incluye las modificaciones humanas aceptadas en los archivos de destino anteriores que proporciones.

Traducir documentos detalla los campos y las reglas de reutilización. Antes de publicar, compara la revisión del archivo de origen del trabajo con tu archivo de origen actual y comprueba si los archivos de destino se han modificado después del envío. Crear un flujo de trabajo de traducción explica ese paso de aceptación.