하나 이상의 컴포넌트 스키마에 속한 게시된 모든 문서를 하나 이상의 대상 언어로 백그라운드에서 번역하도록 대기열에 추가합니다. 각 번역이 완료될 때마다 결과가 translations 테이블에 업서트됩니다.

엔드포인트: POST /translation 인증: Bearer JWT (WorkOS)

요청 본문

{
  "websiteId": "<uuid>",
  "schemaNames": ["post", "hero"],
  "languages": ["fr", "es", "de"]
}

* schemaNames 또는 schemaName 중 하나를 제공해야 합니다.

게시된 콘텐츠가 null이 아닌 게시 문서만 처리 대상으로 고려됩니다.

응답

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es", "de"],
  "status": "queued",
  "documents_processed": 12,
  "translations_scheduled": 30,
  "translations_skipped": 6,
  "translations_completed": 0,
  "translations_failed": 0,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:00:00Z"
}

반환되는 응답:

• 번역이 대기열에 추가되면 202 Accepted
• 모든 번역이 이미 최신 상태이면 200 OK
• 동일한 요청이 이미 실행 중이면 기존 활성 작업

가능한 작업 상태는 다음과 같습니다.

• preparing — 준비 중
• queued — 대기 중
• running — 실행 중
• completed — 완료
• completed_with_errors — 오류와 함께 완료
• failed — 실패

최신 번역 건너뛰기

각 문서-언어 쌍에는 원본 문서의 게시된 콘텐츠에 대한 SHA-256 해시가 저장됩니다.

저장된 원본 해시가 현재 게시된 콘텐츠와 일치하면 번역을 건너뜁니다. 이를 통해 변경되지 않은 콘텐츠를 다시 번역하지 않고 엔드포인트를 반복해서 호출할 수 있습니다.

동일한 작업이 활성 상태인 동안 게시된 콘텐츠가 변경되면 서비스는 새 요청을 거부합니다. 활성 작업이 완료된 후 다시 제출하세요.

처리 동작

번역은 최초 응답 이후 비동기적으로 실행됩니다.

• 작업은 제한된 동시성으로 처리됩니다.
• 일시적인 실패는 백오프를 적용하여 재시도됩니다.
• 성공한 결과는 완료되는 즉시 저장됩니다.
• 개별 추론 또는 저장 실패는 작업에 기록됩니다.
• 일부만 성공한 작업은 completed_with_errors 상태로 완료됩니다.

예시

curl -X POST '{TRANSLATION_API_URL}/translation' \
  -H 'Authorization: Bearer <workos-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "<uuid>",
    "schemaNames": ["post", "hero"],
    "languages": ["fr", "es"]
  }'

오류

• 400 Bad Request — 스키마 또는 언어가 누락되었거나, 지원되지 않는 언어이거나, 배치가 구성된 한도를 초과했습니다.
• 401 Unauthorized — bearer 토큰이 없거나 유효하지 않습니다.
• 409 Conflict — 일치하는 작업이 활성 상태이지만 게시된 원본 콘텐츠가 변경되었습니다.
• 500 Internal Server Error — 원본 문서를 준비할 수 없거나 데이터베이스 작업에 실패했습니다.

번역 작업 조회

번역 작업의 최신 진행 상황을 조회합니다.

엔드포인트: GET /translation-jobs/{job_id} 인증: Bearer JWT (WorkOS)

응답

응답에는 POST /translation에서 반환된 것과 동일한 작업 객체가 사용되며, 상태 및 진행률 수가 업데이트됩니다.

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es"],
  "status": "running",
  "documents_processed": 12,
  "translations_scheduled": 24,
  "translations_skipped": 0,
  "translations_completed": 16,
  "translations_failed": 1,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:01:30Z"
}

예시

curl '{TRANSLATION_API_URL}/translation-jobs/<job-id>' \
  -H 'Authorization: Bearer <workos-jwt>'

오류

• 401 Unauthorized — bearer 토큰이 없거나 유효하지 않습니다.
• 404 Not Found — 작업이 존재하지 않거나 더 이상 보관되지 않습니다.

현재 번역 작업은 메모리에 보관됩니다. 번역 서비스가 재시작되면 작업 상태가 손실되며, 여러 인스턴스로 배포하는 경우 고정 라우팅이 필요합니다.