번역 작업
하나 이상의 문서와 대상 언어를 포함한 작업을 만들고 시작하세요.
작업은 하나의 로컬라이제이션 엔진으로 문서를 번역합니다. 각 문서에는 일관되게 유지되는 키가 있으며, 요청한 언어마다 하나의 번역 대상이 지정됩니다. 메모리에 있는 콘텐츠에는 인라인 JSON을, 파일에는 아티팩트 주소를 사용하세요.
아래의 모든 경로는 https://api.lingo.dev 및 API 인증을 사용합니다.
작업 만들기 #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "order-confirmation.json",
"format": { "type": "json" },
"source": { "content": { "subject": "Your order is confirmed" } }
}
]
}요청 필드 #
| 필드 | 필수 여부 | 설명 |
|---|---|---|
engineId | 예 | 호출자가 번역에 사용할 수 있는 조직 내 엔진입니다. |
sourceLocale | 예 | 원본 언어입니다. |
targetLocales | 예 | 중복 없는 대상 로캘로 구성된 배열로, 비어 있을 수 없습니다. 문서의 원본 로캘을 해당 문서의 대상 로캘로 지정할 수 없습니다. |
documents | 예 | 고유한 key 값을 가진 문서의 배열로, 비어 있을 수 없습니다. |
originId | 아니요 | 문서가 있는 위치를 나타내는 최대 512자의 식별자로, 비어 있을 수 없습니다. 예: github:acme/web. 이 식별자를 통해 해당 위치에서 이후에 이루어지는 편집을 번역 측정과 연결합니다. |
각 문서에는 다음 필드가 있습니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
key | 예 | 논리적 파일 경로 또는 이름입니다. 비어 있을 수 없으며, 이 작업 내에서 고유해야 합니다. 개정 후에도 동일하게 유지하세요. |
format | 예 | type 및 형식별 options 항목을 포함하는 형식 객체입니다. |
source | 예 | SHA-256 아티팩트 주소입니다. 인라인 JSON을 사용하는 경우에는 { "content": { ... } }입니다. |
previousSource | 아니요 | 이전 원본의 아티팩트 주소입니다. 처음 번역하는 경우에는 생략하거나 null을 사용하세요. |
previousTranslations | 아니요 | { "locale": "de", "artifact": "SHA256" }의 배열입니다. 기본값은 []이며, 각 로캘은 중복되지 않아야 하고 이 문서의 대상 로캘에 속해야 합니다. |
targetLocales | 아니요 | 이 문서에 별도로 적용할 로캘 목록입니다. 비어 있을 수 없으며 중복을 허용하지 않습니다. 생략하거나 null을 사용하면 작업의 대상 로캘이 적용됩니다. |
keyScope 또는 termScope을 사용하는 경우 모든 대상에 대해 이전 번역을 제공하세요. 문서 형식 및 업데이트를 참고하세요.
멱등성 #
비어 있지 않은 최대 255자의 Idempotency-Key을 보내세요. 키는 엔진 단위로 적용되며, content-sync: 접두사는 예약되어 있습니다. 키를 원래 요청과 함께 보관하고, 생성 응답이 불확실하면 해당 요청을 변경 없이 다시 보내세요.
키를 재사용하면 해당 키로 처음 생성한 작업이 반환됩니다. 기존 작업의 문서나 로캘은 업데이트되지 않습니다. 작업 내용이 바뀌면 새 키를 사용하세요. 실행 옵션이 충돌하면 LocalizationJobIdempotencyKeyReused(422)가 발생할 수 있습니다.
생성 응답 #
생성에 성공하면 HTTP 200과 작업 응답이 반환되며, 일반적으로 status: { "_tag": "Pending" }이 포함됩니다. 다음 단계로 넘어가기 전에 id을 영구 저장하세요. uploads 배열에는 누락된 입력 아티팩트가 { "address": "...", "uploadUrl": "..." } 형태로 나열됩니다.
작업을 생성하면 인라인 원본이 저장됩니다. uploads이 비어 있어도 번역이 시작되지는 않습니다.
업로드 및 시작 #
원본 바이트가 담긴 인증된 PUT 요청으로 누락된 각 아티팩트를 해당 uploadUrl에 업로드하세요. 업로드가 끝나면 다음을 호출하세요.
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY시작 요청에는 본문이 없습니다. HTTP 200 응답으로 현재 작업 레코드가 반환됩니다. 같은 작업에 시작 요청을 반복해도 안전하며, 실행 요청의 전달 여부가 불확실할 때도 복구할 수 있습니다. 새 작업을 생성하거나 완료된 작업을 다시 실행하지는 않습니다.
시작 시 업로드된 아티팩트, 엔진 구성, 계정 한도를 확인합니다. ArtifactsNotUploaded(409)에는 누락된 입력이 나열됩니다. 일일 토큰 한도(429)에 도달하거나 크레딧이 부족하면 작업은 대기 상태로 유지됩니다. 원인을 해결한 뒤 다시 시작하세요. 오류를 참고하세요.
파이프라인 단계 구성 #
작업을 시작하기 전에 엔진의 파이프라인을 구성하세요. 시작 시점의 구성이 저장됩니다. 작업에 최종 반영된 대상별 단계에는 요금제별 이용 가능 여부에 따라 실제로 선택된 처리 내용이 표시됩니다.
결과 수집 및 복구 #
작업을 조회하여 각 대상을 확인하고 완료된 파일을 다운로드하세요. 단계별 진행 상황에서 모델 처리, 검토 대기, 건너뛴 처리, 실패를 구분할 수 있습니다.
실패한 작업에도 완료된 대상이 있을 수 있습니다. 해당 결과물은 보관하고, 원인을 해결한 뒤 다시 생성해야 하는 내용만 새 멱등성 키로 제출하세요. 나중에 전달된 결과가 더 최신 번역을 덮어쓰지 않도록 원본 개정본을 작업 식별자와 함께 보관하세요.
작업 목록을 조회하여 엔진, 상태, 트리거 또는 서비스 키별로 제출된 작업을 찾으세요.