Localize

문자열 하나, 혹은 작은 문자열 객체를 지금 당장 다른 언어로 바꿔야 할 때가 있습니다. 폼 라벨, 알림, 사용자가 기다리고 있는 짧은 UI 카피처럼요. 이런 경우 단 한 번의 왕복을 위해 웹훅 엔드포인트를 돌리거나 작업 상태를 폴링하고 싶지는 않을 겁니다. 텍스트를 보내고, 번역 결과를 바로 받아오고 싶을 뿐이죠.

이럴 때 쓰는 것이 바로 동기식 Localize 엔드포인트입니다. 한 번 요청하면, 같은 구조의 번역된 데이터가 그대로 돌아옵니다. 소스 로캘과 대상 로캘을 지정해 키-값 콘텐츠를 POST하면, 엔진이 번역을 마칠 때까지 호출은 대기하고, 응답으로는 값만 번역되고 구조는 그대로인 동일한 객체가 반환됩니다. 추적할 작업도 없고, 다시 호출할 필요도 없습니다.

이 번역은 일반적인 모델 호출이 아닙니다. 설정해 둔 로컬라이제이션 엔진의 glossary, 브랜드 보이스, instructions, 그리고 로캘별 model selection을 그대로 거치며, async API와 동일한 엔진을 사용합니다. 차이는 오직 제공 방식뿐입니다. async는 하나의 요청을 여러 로캘로 확장해 결과가 준비되는 대로 전달하고, 이 호출은 하나의 로캘 쌍만 처리해 인라인으로 반환합니다.

이 페이지에서 다루는 내용

• 요청
• 응답
• 예시
• 로컬라이제이션 중 일어나는 일
• 다음 단계

요청#

POST /process/localize

X-API-Key 헤더로 인증합니다. 키는 조직 범위로 발급되며, 조직의 모든 엔진에 접근할 수 있습니다. 키 생성 위치는 Authentication에서, 전체 오류 모델은 Errors and status codes에서 확인하세요.

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

응답#

응답에는 전송한 것과 같은 구조의 번역된 콘텐츠와, 이를 생성한 모델, 그리고 요청별 비용이 함께 담깁니다. 같은 키가 같은 중첩 구조로 그대로 돌아오므로, 코드에서는 이미 알고 있는 구조에서 번역값만 바로 읽어오면 됩니다.

usage 객체는 호출 비용을 항목별로 보여주므로, 별도의 청구 조회 없이도 비용을 바로 귀속할 수 있습니다.

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

예시#

같은 호출을 다섯 가지 언어로 보여줍니다. 이해를 돕기 위해 각 예제는 평면 객체를 사용하지만, data는 중첩 객체와 배열도 지원하며 응답은 전송한 구조 그대로 반환됩니다.

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: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

로컬라이제이션 중 일어나는 일#

하나의 POST 뒤에는 여러 단계가 숨어 있습니다. 그리고 그 단계를 이해할 만한 이유가 있습니다. 바로 이 과정 덕분에 결과물이 일회성 모델 추측이 아니라, 나머지 로컬라이즈된 콘텐츠와 일관된 출력으로 이어지기 때문입니다. 요청이 엔드포인트에 도달하면 엔진은 전체 구성을 다음 순서대로 적용합니다.

1. 모델 선택 – 로캘 쌍에 맞는 최우선 LLM model을 선택합니다. 로캘별 모델이 와일드카드(*) 모델보다 우선합니다. 기본 모델이 실패하면 엔진은 자동으로 다음 순위의 모델로 넘어갑니다.

2. 브랜드 보이스 – 대상 로캘에 맞는 브랜드 보이스를 불러오고, 로캘별 설정이 없으면 와일드카드 브랜드 보이스로 대체합니다.

3. 지침 – 와일드카드 지침을 포함해 대상 로캘과 일치하는 모든 instruction을 불러옵니다.

4. 용어집 조회 – 입력 값을 검색 가능한 청크로 나누고 임베딩을 생성한 뒤, 엔진의 glossary를 대상으로 벡터 유사도 검색을 수행합니다. 일치한 용어는 정확한 번역을 강제하거나, 번역 불가 용어로 표시해 원문 그대로 통과시킵니다.

5. 생성 – 구성된 프롬프트를 선택된 모델로 보내고, 이후 JSON 응답을 파싱하고 검증합니다.

이 과정은 async API가 작업별로 실행하는 엔진 단계 파이프라인과 동일합니다. sync를 호출하든 async를 호출하든 달라지는 것은 전달 방식뿐이지, 번역이 만들어지는 방식은 아닙니다. 그래서 여기서 번역된 문자열과 async 작업에서 번역된 같은 문자열은 동일한 glossary 용어와 동일한 보이스를 따르게 됩니다.

다음 단계#