Automatize a localização de arquivos com a API

Envie um arquivo de origem, inicie uma tarefa de documento e baixe as traduções em um diretório de saída separado.

Use a API de documentos quando seu backend gerenciar os arquivos e precisar coordenar a tradução com o próprio armazenamento. Este exemplo traduz messages/en.json para alemão e francês. A CLI realiza as mesmas operações com arquivos em um projeto local.

Você precisa do Node.js 22 ou posterior, de uma organização, de um engine configurado com um modelo e de uma chave de API com acesso à tradução. Nesta primeira execução, configure a tradução sem revisão humana; adicione a revisão depois que o ciclo de vida dos arquivos estiver funcionando.

Prepare um arquivo de origem #

Crie messages/en.json:

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

Defina as seguintes variáveis de ambiente com seus próprios 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"

Mantenha o mesmo ID de solicitação ao tentar novamente com esta origem e configuração. Altere-o ao enviar uma nova revisão.

Envie, inicie e obtenha os resultados #

Salve 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`);
}

Execute node translate-file.mjs e confira translated/de.json e translated/fr.json. Ambos devem preservar as chaves do arquivo de origem e conter o texto no idioma correspondente. O programa mantém os arquivos de saída separados dos arquivos da aplicação para que você possa revisá-los antes de substituir o conteúdo aceito.

Retome sem duplicar a tarefa #

file-job.json registra a identificação remota e o hash da origem. Se a resposta ao envio ou à solicitação de início se perder, recupere essa tarefa, envie os artefatos restantes e repita a solicitação de início. Repetir a criação com a chave de idempotência original também retorna a mesma tarefa.

Atingir o tempo limite das consultas periódicas não cancela o trabalho. Continue consultando a tarefa registrada; não crie outra só porque o programa local parou de esperar.

Este exemplo para ao encontrar o primeiro destino incompleto ou a primeira solicitação com falha. Os arquivos já salvos permanecem em translated/. Para continuar, recupere a tarefa registrada em file-job.json e baixe os destinos concluídos usando seus valores de downloadUrl; consulte estado e resultados da tarefa. Uma falha no download não exige uma nova tarefa de tradução.

Adicione atualizações incrementais #

Na próxima revisão, forneça previousSource e previousTranslations junto com o novo endereço de origem. Mantenha os bytes de cada artefato referenciado até que o envio seja concluído com sucesso. Inclua as edições humanas aceitas nos arquivos de destino anteriores que você fornecer.

Traduzir documentos apresenta os campos e as regras de reutilização. Antes de publicar, compare a revisão de origem da tarefa com a versão atual da origem e verifique se os destinos foram editados após o envio. Criar um workflow de tradução explica essa etapa de aceitação.