Lingo.dev 로컬라이제이션 API는 설정된 로컬라이제이션 엔진을 통해 키-값 데이터를 번역합니다. HTTP 호출 한 번이면 문자열을 보내고, 용어집 규칙, 브랜드 보이스, 모델 선택이 자동으로 적용된 번역 결과를 받아볼 수 있습니다.
API를 사용해야 할 때#
번역이 빌드 타임이 아니라 런타임이나 백엔드 서비스에서 이뤄진다면 로컬라이제이션 API를 사용하세요.
| 사용 사례 | 예시 |
|---|---|
| 동적 콘텐츠 | 데이터베이스에 저장된 강의 설명, 수업 제목, 퀴즈 질문 번역 |
| 사용자 생성 콘텐츠 | 리뷰, 댓글, 포럼 게시물을 필요할 때마다 번역 |
| API 응답 | 사용자의 로캘에 맞춰 백엔드에서 로컬라이즈된 콘텐츠 반환 |
| 알림 | 이메일 제목, 푸시 알림, 앱 내 메시지를 전송 전에 번역 |
빌드 타임 vs 런타임
콘텐츠가 정적 파일(JSON, Markdown, .strings)에 있다면 CLI나 CI/CD integration이 더 적합합니다. API는 백엔드에서 콘텐츠를 로컬라이즈하도록 설계되었습니다.
사전 준비#
로컬라이제이션 엔진 만들기
모든 API 호출은 로컬라이제이션 엔진을 통해 처리됩니다. 이 엔진은 어떤 LLM 모델, 용어집, 브랜드 보이스, 지침을 적용할지 결정하는 설정입니다. Lingo.dev 대시보드에서 생성할 수 있습니다.
콘텐츠 로컬라이즈하기#
source 로캘, target 로캘, 키-값 데이터를 포함해 localize 엔드포인트로 POST 요청을 보내세요. 전체 요청/응답 스키마는 API reference에서 확인할 수 있습니다.
이 예시에서는 JavaScript 강의의 한 문단을 스페인어로 번역합니다:
const content = {
intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": "your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
engineId: "eng_abc123",
sourceLocale: "en",
targetLocale: "es",
data: content,
}),
});
const { data } = await response.json();
// {
// intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }키는 그대로 유지됩니다. intro을 보내면 intro이 돌아옵니다. 엔진은 값만 번역합니다.
키 구조화하기#
data 객체는 평평한 구조로, 각 키는 하나의 문자열에 매핑됩니다. 의미 맥락이 드러나도록 키를 구성하세요:
const content = {
"variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
"variables.example": "Use const for values that never change, and let for values that do.",
"variables.exercise": "Declare a variable called age and assign it your age as a number.",
};의미적으로 묶인 키는 로컬라이제이션 엔진이 더 자연스럽고 일관된 번역을 만드는 데 도움이 됩니다. 엔진은 하나의 요청에 포함된 모든 키를 서로 관련된 맥락으로 보기 때문에, variables.intro과 variables.example은 따로 보낼 때보다 함께 보낼 때 더 일관되게 번역됩니다.
기술 용어
"const"나 "let" 같은 용어는 번역하면 안 되는 프로그래밍 용어입니다. 용어집을 사용해 번역 제외 용어로 지정하거나, 로캘별 대응 표현으로 매핑하세요. Claude Code나 Cursor 같은 AI 코딩 도우미를 사용한다면 Localization MCP를 통해 개발 워크플로의 일부로 용어집 규칙을 설정하는 데 도움을 받을 수 있습니다.
저장 시점에 로컬라이즈하기#
일반적으로는 콘텐츠를 읽을 때가 아니라 생성되거나 업데이트될 때 번역합니다. 이렇게 하면 사용자가 콘텐츠를 요청할 때는 이미 번역된 내용이 데이터베이스에 저장되어 있습니다.
app.post("/api/lessons", async (req, res) => {
const lesson = await db.lessons.create(req.body);
const content = {
intro: lesson.intro,
example: lesson.example,
exercise: lesson.exercise,
};
const targetLocales = ["es", "fr", "de", "ja"];
const translations = await Promise.all(
targetLocales.map(async (targetLocale) => {
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": process.env.LINGODOTDEV_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
sourceLocale: "en",
targetLocale,
data: content,
}),
});
const { data } = await response.json();
return { locale: targetLocale, data };
})
);
await db.lessonTranslations.insertMany(
translations.map((t) => ({
lessonId: lesson.id,
locale: t.locale,
...t.data,
}))
);
res.json(lesson);
});그러면 로컬라이즈된 콘텐츠를 읽는 일은 단순한 데이터베이스 조회로 끝나며, 조회 시점에는 API 호출이 필요하지 않습니다:
app.get("/api/lessons/:id", async (req, res) => {
const locale = req.query.locale || "en";
if (locale === "en") {
const lesson = await db.lessons.findById(req.params.id);
return res.json(lesson);
}
const translation = await db.lessonTranslations.findOne({
lessonId: req.params.id,
locale,
});
res.json(translation);
});