API로 파일 현지화 자동화하기

소스 파일을 업로드하고 문서 작업을 시작한 뒤, 번역 파일을 별도의 출력 디렉터리에 다운로드하세요.

백엔드에서 파일을 관리하며 자체 저장소와 연계해 번역을 처리해야 한다면 문서 API를 사용하세요. 이 예제에서는 messages/en.json을 독일어와 프랑스어로 번역합니다. CLI로도 로컬 프로젝트에서 동일한 파일 작업을 수행할 수 있습니다.

Node.js 22 이상, 조직, 모델이 설정된 엔진, 번역 권한이 있는 API 키가 필요합니다. 처음 실행할 때는 휴먼 리뷰 없이 번역하도록 설정하세요. 파일 처리 과정이 정상적으로 작동하면 검토를 추가하세요.

소스 파일 준비하기 #

messages/en.json을 만드세요:

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

다음 환경 변수를 사용 환경에 맞는 값으로 설정하세요:

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"

같은 소스와 설정으로 재시도할 때는 동일한 요청 ID를 사용하세요. 새 수정본을 제출할 때는 요청 ID를 변경하세요.

업로드, 작업 시작, 결과 수집하기 #

이 프로그램을 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`);
}

node translate-file.mjs을 실행한 뒤 translated/de.json과 translated/fr.json을 확인하세요. 두 파일 모두 소스의 키가 유지되고 내용은 해당 언어로 번역되어 있어야 합니다. 프로그램은 출력 파일을 애플리케이션 파일과 별도로 보관하므로, 승인된 콘텐츠를 교체하기 전에 결과를 검토할 수 있습니다.

작업 중복 없이 복구하기 #

file-job.json은 원격 작업의 식별 정보와 소스 해시를 기록합니다. 업로드나 작업 시작에 대한 응답이 유실되면 해당 작업을 조회하고, 남은 아티팩트를 업로드한 뒤 시작 요청을 다시 보내세요. 처음 사용한 멱등성 키로 생성 요청을 다시 보내도 동일한 작업이 반환됩니다.

폴링 시간이 초과되어도 작업은 취소되지 않습니다. 기록된 작업을 계속 조회하세요. 로컬 프로그램이 대기를 중단했다는 이유만으로 새 작업을 만들지 마세요.

이 예제는 완료되지 않은 대상이나 실패한 요청을 처음 만나면 중단됩니다. 이미 저장된 파일은 translated/에 그대로 남습니다. 계속하려면 file-job.json에 기록된 작업을 조회하고, 완료된 대상의 downloadUrl 값을 사용해 해당 결과를 다운로드하세요. 작업 상태 및 결과를 참고하세요. 다운로드에 실패해도 새 번역 작업을 만들 필요는 없습니다.

증분 업데이트 추가하기 #

다음 수정본을 제출할 때는 새 소스 주소와 함께 previousSource과 previousTranslations을 제공하세요. 업로드에 성공할 때까지 참조된 모든 아티팩트의 바이트 데이터를 보관하세요. 제공하는 이전 대상 파일에는 사람이 수정한 내용 중 승인된 내용을 반영하세요.

문서 번역하기에서 필드와 재사용 규칙을 확인할 수 있습니다. 게시하기 전에 작업의 소스 수정본을 현재 소스와 비교하고, 제출 이후 대상 파일이 수정되었는지 확인하세요. 이 승인 단계는 번역 워크플로 구축하기에서 설명합니다.