번역 API 워크플로 구축하기
서버에서 애플리케이션 레코드를 번역하고, 승인된 언어별 버전을 해당 원문 리비전과 연결해 관리하세요.
편집자가 제품 설명을 수정하면 각 번역본에도 변경 사항이 반영되어야 합니다. API 응답은 새 텍스트를 제공하고, 애플리케이션은 이 텍스트가 어느 레코드에 속하는지, 원문이 여전히 최신 상태인지, 독자에게 언제 공개할지를 결정합니다.
이 가이드에서는 첫 번역 요청을 반복 실행할 수 있는 백엔드 워크플로로 확장합니다. 애플리케이션에서 직접 관리하는 제품 설명이나 도움말 항목 같은 레코드에 적합합니다. 정적 애플리케이션 리소스에는 CI 파일 워크플로가 더 적합한 경우가 많습니다. 리소스 컴파일과 저장소 검토 과정에서 이미 유효성을 확인할 수 있기 때문입니다.
맥락이 이어지는 콘텐츠를 하나로 묶어 보내기 #
제품 레코드를 담은 인라인 JSON 문서 하나로 로컬라이제이션 작업을 생성하세요. 맥락을 통해 각 필드의 용도를 설명할 수 있도록 관련 필드를 묶고, 다운로드한 객체를 원래 필드에 대응시킬 수 있도록 키를 일관되게 유지하세요.
API 키와 이 리비전에 고정적으로 사용할 Idempotency-Key를 지정해 다음 본문을 POST /v2/organizations/:orgId/localization/jobs에 제출하세요:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}인증 정보는 백엔드에 보관하고 엔진을 명시적으로 선택하세요. 제품 용어에는 공통 용어집 지침을 적용하고, 이번 용도에 맞는 문서 맥락을 제공하세요. 힌트와 보호 경로에 관한 내용은 JSON 레퍼런스에서 확인할 수 있습니다.
백그라운드 작업으로 번역 실행하기 #
작업을 시작하기 전에 반환된 작업 ID를 저장하세요. uploads에 나열된 항목을 모두 업로드한 다음 POST /v2/localization/jobs/:id/start를 호출하세요. 인라인 JSON도 이처럼 명시적으로 시작해야 합니다.
백엔드 워커에서 작업 상태를 주기적으로 조회하고, 반환된 URL로 완료된 대상 언어의 결과를 다운로드하세요. 애플리케이션이 이 작업을 큐에 영구적으로 저장하면 편집자의 저장 요청에 응답할 수 있습니다. 번역이나 사람이 하는 검토가 진행되는 동안 요청을 계속 열어 둘 필요는 없습니다.
증분 업데이트를 하려면 이전 원문과 승인된 번역 결과물을 보관하고 다음 문서 요청에 함께 제공하세요. 재사용 범위는 문서 업데이트에서 설명합니다.
원문을 저장한 뒤 작업 기록하기 #
원문 트랜잭션이 커밋되면 자체 저장소에 콘텐츠 ID, 원문 리비전, 대상 로캘, 로컬라이제이션 엔진/구성 레코드, 처리 상태를 담은 작업 레코드를 생성하세요. 이 레코드를 바탕으로 번역 작업을 큐에 넣으세요. 이렇게 하면 원문 트랜잭션에서 나중에 롤백될 수정 내용을 워커가 번역하는 일을 방지할 수 있습니다.
대상 언어마다 결과를 따로 기록하세요. 독일어는 준비되었지만 프랑스어는 재시도나 검토가 필요할 수 있습니다. 전체 상태를 ‘번역됨’ 플래그 하나로만 기록하면 어떤 내용을 제공할지 결정하는 애플리케이션이 이 차이를 알 수 없습니다. 직접 추가한 상태 이름은 애플리케이션 설계의 일부이며, API 응답에서 사용하는 용어가 아닙니다.
의도한 리비전의 결과만 승인하기 #
원문 수정 순서와 번역 완료 순서는 다를 수 있습니다. 다음 상황을 살펴보세요:
| 이벤트 | 애플리케이션 동작 |
|---|---|
| 리비전 12 저장 | 리비전 12의 독일어 번역을 큐에 넣습니다. |
| 해당 작업이 끝나기 전에 리비전 13 저장 | 리비전 13을 큐에 넣고 현재 원문으로 표시합니다. |
| 리비전 13의 번역 완료 | 유효성을 확인하고 리비전 13의 번역으로 승인합니다. |
| 리비전 12의 번역이 뒤늦게 완료 | 리비전 13의 승인된 텍스트를 대체하지 않고 기록된 결과를 보관합니다. |
활성화 시점에 작업 레코드의 원문 리비전과 현재 원문의 리비전을 비교하세요. 저장소 시스템에서 해당 리비전을 조건으로 비교와 쓰기를 수행해, 두 작업 사이에 원문이 다시 수정되어도 이를 놓치지 않도록 하세요. 현재 리비전의 작업이 큐에 등록되지 않았거나 실패했다면 이전 결과의 리비전 표시를 바꾸지 말고 현재 리비전의 작업을 예약하세요.
읽기 시점에는 요청된 언어와 리비전에 대해 승인된 번역을 조회하세요. 번역이 없을 때 애플리케이션이 어떻게 동작할지도 결정하세요. 원문을 표시하거나, 지정된 대체 언어를 사용하거나, 명시적으로 추적·관리하는 이전 번역을 제공하거나, 게시를 보류할 수 있습니다. 적절한 선택은 오래되거나 번역되지 않은 텍스트가 독자에게 어떤 영향을 줄 수 있는지에 따라 달라집니다. 결제 조건이 변경된 경우에는 일반적인 제품 설명보다 엄격한 정책이 필요할 수 있습니다.
원격 식별 정보와 로컬 기록으로 복구하기 #
요청을 보내기 전에 멱등성 키를 영구 저장하고, 생성 응답을 받는 즉시 작업 ID도 영구 저장하세요. 네트워크 시간 초과가 발생하면 같은 키로 생성 요청을 변경 없이 다시 보내거나 기록된 작업을 조회하세요. 시작 호출을 반복해도 동일한 작업에 적용됩니다.
일시적으로 조회에 실패하면 재시도 간격을 늘려 가며 상태를 조회하세요. 클라이언트의 대기 기한이 지나면 대기만 중단될 뿐, 서버 작업은 중단되지 않습니다. 완료된 대상 언어의 결과물과 실패한 대상 언어의 세부 정보는 따로 보관하세요. 실패한 작업에도 사용할 수 있는 완료 파일이 포함되어 있을 수 있습니다.
인증 오류, 비활성화된 엔진, 잘못된 입력, 계정 한도 문제는 바로잡아야 합니다. 대기 중인 작업은 접수 한도 문제가 해결된 뒤 다시 시작할 수 있습니다. 실행 중 실패한 작업은 원인을 해결한 다음, 영향을 받은 문서와 로캘을 새 멱등성 키로 제출하세요.
승인할 때는 복구 후 조회한 결과를 포함해 모든 결과에 동일한 리비전 확인 절차를 적용하세요. 다운로드가 완료되었다는 것은 텍스트가 확보되었다는 뜻입니다. 게시 가능 여부는 유효성 확인 및 검토 정책에 따라 결정됩니다.
레코드 수명 주기 테스트하기 #
변수가 포함된 짧은 레코드로 원문 업데이트, 특정 로캘의 실패, 순서가 뒤바뀐 작업 완료 상황을 테스트하세요. 텍스트뿐 아니라 저장된 필드 키와 언어 식별 정보도 확인하세요. 애플리케이션은 정책에 따라 승인된 버전만 제공해야 하며, 검토자는 해당 버전을 원문까지 추적할 수 있어야 합니다.
품질을 측정하려면 원문과 번역문 쌍을 평가에 사용한 기준과 함께 보관하세요. 측정 설계는 생성 워크플로와 독립적으로 적용됩니다. 이렇게 하면 레코드에서 텍스트 반환, 측정 응답, 사람의 승인, 게시를 하나의 이벤트로 취급하지 않고 각각 구분할 수 있습니다.