지금 로컬라이제이션 엔진을 세팅하고 있다면, 잘 번역하는 엔진은 비어 있는 엔진이 아닙니다. 브랜드 보이스, 용어집, 지침이 담긴 엔진이 좋은 번역을 만듭니다. 그래야 모든 번역이 제품의 말투를 그대로 살리고, 이미 정해 둔 용어도 흐트러뜨리지 않습니다.
이런 지식은 대개 엔진보다 먼저 준비되어 있습니다. 브랜드 가이드라인 페이지, 스타일 가이드, 용어 정리 문서, 예전에 번역가에게 전달했던 몇 단락의 규칙 같은 곳에 이미 담겨 있죠. 엔진을 손수 구성하려면 그 모든 내용을 읽고 브랜드 보이스, 용어집, 지침 레코드로 하나씩 다시 입력해야 합니다. 시작은 쉽지만, 중간에 하다 만 채로 남기기 쉬운 지루한 작업입니다.
비동기 프로비저닝 API는 이 간극을 메워 줍니다. 이미 갖고 있는 자료를 그대로 지정하세요. 링크와 원문 텍스트를 한 번의 요청으로 POST하면 엔진 ID를 즉시 돌려받고, AI 에이전트가 소스를 크롤링해 브랜드 보이스, 용어집 항목, 지침을 추출한 뒤 확인되는 즉시 새 엔진에 적용합니다. 엔진은 ID를 받는 순간부터 바로 사용할 수 있고, 작업이 진행되는 동안 구성이 차례대로 채워집니다.
이 페이지에서 다루는 내용
문제#
로컬라이제이션 엔진의 품질은 결국 구성에 달려 있습니다. 모델 선택만으로도 번역은 만들 수 있지만, 그 번역을 제품이 원래 말하던 방식에 맞게 만드는 것은 브랜드 보이스, 용어집 항목, 지침입니다. 예를 들면 선택한 격식 수준, 절대 번역하지 않는 제품명, 항상 사용하는 날짜 형식 같은 것들이죠. 그리고 이것들은 원래라면 직접 하나씩 만들어야 하는 동일한 구성 요소이기도 합니다. 바로 브랜드 보이스, 용어집 항목, 지침, 그리고 엔진에 들어가는 설정입니다.
문제는 이 모든 정보가 이미 어딘가에 존재한다는 점입니다. 한 언어로 제품을 출시한 팀이라면 브랜드 가이드라인 페이지도 있고, 스타일 가이드도 있고, 고객 지원 담당자에게 절대 번역하지 말라고 안내하는 용어집도 이미 갖고 있습니다. 엔진을 수동으로 구성하려면 그 문서들을 읽고, 결정 하나하나를 로캘별로 레코드에 옮겨 적어야 합니다. 느릴 수밖에 없고, 그중 가장 느린 부분은 가장 흥미롭지 않은 일입니다. 이미 적어 둔 지식을 그저 다른 형식으로 다시 옮기는 일이니까요.
프로비저닝은 그 단계를 없애 줍니다. 플랫폼에 문서 자체를 넘기면 됩니다. 크롤링할 URL이든 원문 텍스트든 상관없습니다. 그러면 AI 에이전트가 읽고 옮겨 적는 작업을 대신합니다. 실제 엔진에 브랜드 보이스, 용어집, 지침 레코드를 만들고, 식별되는 즉시 각각 적용합니다. 이후에는 대시보드에서 직접 만든 항목을 수정하듯 같은 방식으로 검토하고 조정하면 됩니다. 시작점은 빈 엔진이 아니라 이미 구성된 엔진입니다.
프로비저닝은 엔진을 구성하지만, 번역을 하지는 않습니다.
이 API는 엔진을 만들고 구성하는 역할을 합니다. 엔진이 준비된 뒤 실제로 번역하려면, 여러 로캘을 한 번에 처리할 때는 비동기 Localization API를, 단일 로캘 쌍에는 동기 Localize 엔드포인트를 사용하세요. 프로비저닝은 첫 번역부터 브랜드 보이스와 용어집이 반영되도록 해 주는 준비 단계입니다.
작동 방식#
단계는 세 가지이며, 이 중 요청 안에서 일어나는 일은 첫 번째뿐입니다. 나머지 두 단계는 플랫폼에서 비동기로 진행되기 때문에 호출은 즉시 반환되고, 작업이 끝나기 전에도 엔진을 사용할 수 있습니다.
소스 제출
새 엔진의 이름과 소스 배열을 /jobs/provisioning로 POST하세요. 소스에는 크롤링할 URL, 분석할 원문 텍스트, 또는 둘 다 들어갈 수 있습니다. API는 즉시 엔진을 생성하고, 엔진 ID(eng_)와 작업 ID(pjb_)가 담긴 202를 반환합니다. 애플리케이션은 그대로 다음 작업을 진행하면 되고, 응답은 추출 완료를 기다리지 않습니다. 전체 요청/응답 형식은 프로비저닝 작업 생성에서, 어떤 소스를 제출하면 좋은지는 소스 유형에서 확인하세요.
AI 에이전트가 크롤링하고 추출합니다
링크 소스는 병렬로 크롤링되어 텍스트로 변환되고, 원문 콘텐츠는 그대로 직접 읽습니다. 그런 다음 AI 에이전트가 전체 내용을 분석해 세 가지 구성 요소인 브랜드 보이스, 용어집 항목, 지침을 추출하고, 식별되는 즉시 각각 엔진에 적용합니다. 일부 소스의 크롤링이 실패하거나 개별 항목을 생성하지 못해도 나머지 작업은 멈추지 않습니다. 이 세 가지 구성 요소와 로캘에 매핑되는 방식은 AI가 추출하는 내용에서 자세히 다룹니다.
엔진이 준비됩니다
추출이 끝나면 엔진은 완전히 구성된 상태가 되며 Localization API를 통해 번역할 준비를 마칩니다. 플랫폼은 생성된 항목 전체 요약과 함께 완료 상태를 webhook URL로 보내고, 실행 중 진행 상황을 보여 주고 싶다면 job's WebSocket을 통해 실시간으로 받을 수도 있습니다.
엔진 ID는 즉시 사용할 수 있습니다.
202에 들어 있는 eng_ ID는 받는 즉시 실제 엔진을 가리킵니다. 바로 저장하고, 참조하고, 곧바로 번역에 사용할 수 있습니다. 구성은 작업이 진행되는 동안 순차적으로 적용되므로, 초기에 만든 번역은 작업 완료 후의 번역보다 반영된 추출 레코드 수가 적을 수 있습니다. 엔진 사용을 시작하기 위해 프로비저닝 완료를 기다릴 필요는 없습니다.
인증
모든 요청은 REST와 WebSocket 모두 X-API-Key 헤더로 인증합니다. 키는 조직 범위로 적용되며, 해당 조직의 모든 엔진에 접근할 수 있습니다. 자세한 내용은 Authentication에서, 키 생성 방법은 API Keys에서 확인하세요.
돌아오는 결과#
신중한 독자라면 이미 두 가지를 궁금해할 겁니다. 이 기능을 믿고 써도 되는지 판단하게 만드는 질문이죠. 소스 품질이 좋지 않으면 어떻게 되는지, 그리고 내가 수정할 수 없는 블랙박스는 아닌지 말입니다.
두 질문 모두 답이 분명합니다. 프로비저닝은 정체를 알 수 없는 독점 블롭을 반환하지 않습니다. 대신 실제 엔진에 일반적인 브랜드 보이스, 용어집, 지침 레코드를 생성합니다. 모두 원래 직접 만들 수 있는 동일한 객체이며, 이후에도 대시보드에서 각각 수정할 수 있습니다. 작업이 끝나면 생성된 모든 레코드와 발생한 모든 실패를 명시한 요약도 함께 돌아오므로, 막연히 믿는 대신 구성을 직접 확인할 수 있습니다. 이 요약이 어떻게 구성되는지, 그리고 실패한 항목이 어떻게 errors 목록으로 분리되면서도 나머지 엔진 구성은 계속 진행되는지는 AI가 추출하는 내용에서 설명합니다.
소스 제출은 필수가 아닙니다. sources 없이 이름만 제출하면 기본값으로 설정된 깔끔한 엔진이 생성되고, 이후 직접 구성할 수 있습니다. 프로비저닝 작업 생성에서는 이 경로도 202 응답 형식과 함께 다룹니다. 프로비저닝은 수동 설정을 건너뛰게 해 주는 방법이지, 엔진을 만들기 위한 필수 단계는 아닙니다.
일반적인 페이지에서는 일반적인 구성만 나옵니다.
구성 품질은 결국 무엇을 제출하느냐에 달려 있습니다. 브랜드 가이드라인과 용어 목록은 에이전트가 추출할 구체적인 근거를 제공하지만, 마케팅 홈페이지만으로는 거의 아무것도 얻지 못합니다. 무엇을 지정해야 하는지는 소스 유형에서 다룹니다.
이것이 프로비저닝의 교환 조건입니다. 한 번의 요청과 짧은 대기 시간만으로, 이미 문서화해 둔 지식을 다시 옮겨 적는 수작업을 건너뛸 수 있습니다. 이미 갖고 있는 자료를 그대로 지정하고, 구성된 엔진에서 시작하세요. 아래 페이지들은 바로 그 문장을 이루는 각 요소를 설명합니다.
