Automatiza la localización de archivos con la API

Carga 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 administre 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 traducción. Para esta primera ejecución, configura la traducción sin revisión humana; agrega 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"

Mantén el mismo ID de solicitud para los reintentos con este archivo de origen y esta configuración. Cámbialo cuando envíes una nueva revisión.

Carga, inicia y obtén 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 luego revisa translated/de.json y translated/fr.json. Ambos deben conservar las claves del archivo de origen y tener el contenido 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 reemplazar el contenido aceptado.

Recupera el trabajo sin duplicarlo #

file-job.json registra la identidad remota y el hash del archivo de origen. Si se pierde la respuesta de una carga o de una solicitud de inicio, recupera ese trabajo, carga los artefactos que falten y repite la solicitud de inicio. Repetir la creación con la clave de idempotencia original también devuelve el mismo trabajo.

Si se agota el tiempo de espera de las consultas periódicas, el trabajo no se cancela. Sigue consultando el trabajo registrado; no crees otro solo porque el programa local dejó de esperar.

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

Agrega 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 carga se complete correctamente. Incluye las ediciones 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 de origen del trabajo con tu archivo de origen actual y verifica si hubo cambios en los destinos después del envío. Crear un flujo de trabajo de traducción explica ese paso de aceptación.