자바스크립트에서 API 호출하기
Node.js 서버에서 JSON을 번역하고 결과가 나올 때까지 기다린 뒤 파일로 저장하세요.
서버에서 구조화된 콘텐츠를 번역하려면 기본 제공 fetch을 사용하세요. 이 예제에서는 영어로 된 계정 설정 제목을 프랑스어로 번역해 settings.fr.json로 저장합니다. Node.js 22 이상과 번역 모델이 설정된 엔진이 필요합니다.
인증 정보는 서버에 보관하세요. 리액트 런타임은 API 키 없이 카탈로그를 렌더링합니다.
요청 설정하기 #
엔진의 번역 기능에 접근할 수 있는 API 키를 만들고 조직 및 엔진 식별자를 확인하세요. 이 예제에서는 휴먼 리뷰가 비활성화된 엔진을 사용하세요.
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"이 제출 요청을 재시도할 때는 LINGO_REQUEST_ID을 재사용하세요. 원문, 로캘 또는 다른 요청 옵션이 바뀌면 새 값을 사용하세요.
번역하고 결과 저장하기 #
다음 내용을 translate.mjs로 저장하세요:
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");node translate.mjs을 실행한 뒤 settings.fr.json를 열어 프랑스어 제목을 확인하세요. 프로그램은 작업을 시작하기 전에 작업 식별자를 저장하고, 번역 대상의 처리가 완료된 후에만 결과를 다운로드합니다.
요청 도우미는 응답을 읽기 전에 HTTP 상태를 확인합니다. HTTP 오류가 발생하면 상태와 문제 세부 정보를 바탕으로 수정할 내용을 판단하세요. 서버가 작업을 수락한 뒤에도 네트워크 오류나 시간 초과가 발생할 수 있습니다.
중단 후 이어서 진행하기 #
job.json에서 식별자를 읽고 작업을 조회해 상태를 계속 확인하세요. 파일을 저장하기 전에 생성 요청의 응답이 유실되었다면 동일한 멱등성 키로 같은 요청을 다시 보내세요. /start을 다시 실행하면 같은 작업을 이어서 진행합니다. 시간 초과가 발생해도 프로그램의 대기만 종료될 뿐, 서버 작업은 취소되지 않습니다.
많은 제출 요청을 처리하거나 휴먼 리뷰를 기다리는 애플리케이션이라면, 작업 식별자와 원문 리비전을 저장하고 작업자 프로세스에서 결과를 수집하는 번역 워크플로를 구축하세요. 파일 번역하기에서는 여러 언어의 산출물 업로드와 부분 결과를 다룹니다.