자동 번역 API는 번역 타입과 번역기를 간단하게 설정할 수 있는 API입니다. 실시간 동기식 번역과 비동기식 번역을 모두 지원하여 유연한 번역 환경을 제공합니다.

자동 번역 API 종류는 크게 실시간 번역이 가능한 동기 번역 API와 실시간 번역이 불가능한 비동기 번역 요청 API비동기 번역 결과 확인 API가 있습니다.

참고 사항

지원 텍스트 형식

동기 번역 API와 비동기 번역 API에서 지원하는 각 텍스트 형식은 아래와 같습니다.

  • 동기 번역 API: 일반 텍스트 및 HTML 형식 지원
  • 비동기 번역 API: Markdown 형식 지원

프로젝트 매칭 방법

자동 번역 API에서는 앱센터에 등록된 각 게임 프로젝트 별로 번역 서비스를 매칭할 수 있는 두 가지 방법을 제공합니다.

  • 자동 번역 서비스와 1대1 매칭: 각 프로젝트 별로 사용하는 서비스를 등록
  • 하나의 자동 번역 서비스 호출 시, 프로젝트 ID를 입력하여 매칭: 각 프로젝트 ID를 인자 값으로 추가하여 API 호출

번역 지원 언어

Hive에서 지원하는 번역 언어는 총 16가지로 아래와 같습니다.

언어 언어별 표기법 Hive 언어코드
한국어 한국어 ko
영어 English en
일본어 日本語 ja
중국어 간체 简体中文 zh-hans
중국어 번체 繁體中文 zh-hant
프랑스어 Français fr
독일어 Deutsch de
러시아어 русский ru
스페인어 Español es
포르투갈어 Português pt
인도네시아어 Bahasa Indonesia id
베트남어 tiếng Việt vi
태국어 ไทย th
이탈리아어 Italiano it
터키어 Türkçe tr
아랍어 العربية ar

사전 준비 사항

자동 번역 API 사용을 위한 사전 준비 사항은 아래와 같습니다.

1. 서비스키(appKey), 비밀키 확인

  1. Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 서비스를 등록합니다.
  2. 제품에 대한 서비스키(구 앱키)와 비밀키를 확인합니다.

2. Signature(서명) 확인

API 서버의 백오피스에서는 서비스키와 비밀키를 사용하여 Signature(서명)을 생성합니다.

Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 키 관리 선택하여 생성된 서명을 확인합니다. 생성된 서명 코드 예시는 아래와 같습니다.

※ 서명은 앱키와 암호키를 사용하여 HmacSHA256 인코딩한 Base64 값입니다.

Python

Java

동기 번역 API

실시간 동기 방식으로 번역 요청과 번역 결과를 한 개의 API 요청 및 응답으로 처리합니다.
API 응답에서 바로 번역 결과가 제공되기 때문에 번역 결과를 확인하는 API가 존재하지 않습니다.

동기 번역 텍스트 타입으로, 전/후처리가 필요하지 않은 일반 텍스트와 HTML 텍스트 형식을 지원합니다.

Request URL

LIVE URL https://ats.withhive.com/api/translate/sync
https://ats.withhive.com/api/translate/sync/{project_id}
HTTP Method POST
Content-Type application/json
Data Format JSON

Request Path

필드명 설명 타입 필수 여부 상세 예시
project_id 앱센터 프로젝트 ID String N 1. 값이 있는 경우 : 프로젝트 ID로 집계2. 값이 없는 경우 : “없음” 으로 집계 com.com2us.project1

Request Header

필드명 설명 타입 필수 여부 상세 예시
Signature 인증을 위한 서명 값 String Y 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=

Request Body

필드명 설명 타입 필수 여부 상세 예시
info 앱 키 정보 객체 Object Y
info > app_key 앱 키 값 String Y 802890479467404e
info > meta_data 자동번역 서비스에서 집계하지는 않으나, 로그로 저장하는 값 Object N JSON Object String 변환 시, 1kb 이내 {“game” : “MLB”} or [{“key1”:“blabla”}]
text 번역 요청 내용 String Y ※ 문자열 Json 이스케이프 필요 “ \”등록\” 절차에 대한 문의”
from 번역 요청 언어 String Y “text”에 해당하는 언어 코드번역 지원 언어 및 Hive 언어코드 참고

※ “auto” 입력 시, 자동 감지 (소문자)

1. (자동 감지) “auto”2. (한국어) “ko”
to 번역 응답 언어 String Y “,” 구분자로 분리 하여 여러 언어 요청 가능번역 지원 언어 및 Hive 언어코드 참고 1. (단일 언어 번역)“en”2. (다중 언어 번역)“en, fr, de”

Response

필드명 설명 타입 상세 예시
result 결과값 Object
result > code 결과 코드 Integer Response Code 참고 성공 시 ‘200’
result > msg 결과 메시지 String Response Code 참고 성공 시 ‘Success’
content 번역 결과 Object
content > data > translateMsg 번역값 배열 Array
content > data > translateMsg > detectedLanguage 입력 언어 관련 값 Object ※ “번역 요청 언어 (from)“이 “auto” 인 경우 존재
content > data > translateMsg > detectedLanguage > language 입력 언어 감지 값 String 번역 지원 언어 및 Hive 언어코드 참고
content > data > translateMsg > detectedLanguage > score 입력 언어 감지 스코어 (1에 가까울수록 정확) Number (Float) 1.0
content > data > translateMsg > translations 번역 텍스트 배열 Array 언어별 배열로 노출
content > data > translateMsg > translations > text 번역 텍스트 String Json 이스케이프 문자열 Inquiries about the \”Registration\” process
content > data > translateMsg > translations > to 번역 언어 국가 코드 String “en”

Response Code

코드 텍스트 비고
200 “success” 성공
400 <> is Missing or
Incorrect request
실패 – 요청 파라미터 누락 or

실패 – 파싱 불가능 (JSON 오류)

401 Wrong Signature 실패 – 서명 키 이상
404 Unregistered app key 실패 – 등록되지 않은 앱 키
404 Unregistered job uuid 실패 – 등록되지 않은 job uuid
500 Internal Server Error (or Some message) 실패 – 서버 내부 오류

Request Example

Curl

Python

Java

Response Example

비동기 번역 요청 API

비동기 방식의 번역 API는 번역 요청과 번역 응답을 구분하여 두 개의 API로 처리합니다.
크게 요청에 해당하는 ‘비동기 번역 요청 API’와 응답에 해당하는 ‘비동기 번역 결과 확인 API’가 있습니다.

바동기 번역 텍스트 타입으로, 전/후처리가 필요한 마크다운 텍스트 형식을 지원합니다.

Request URL

LIVE URL https://ats.withhive.com/api/translate/async
https://ats.withhive.com/api/translate/async/{project_id}
HTTP Method POST
Content-Type application/json
Data Format JSON

Request Path

필드명 설명 타입 필수 여부 상세 예시
project_id 앱센터 프로젝트 ID String Y 1. 값이 있는 경우 : 프로젝트 ID로 집계2. 값이 없는 경우 : “없음” 으로 집계 com.com2us.project1

Request Header

필드명 설명 타입 필수 여부 상세 예시
Signature 인증을 위한 서명 값 String Y 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=

Request Body

필드명 설명 타입 필수 여부 상세 예시
info 앱 키 정보 객체 Object Y
info > app_key 앱 키 값 String Y 802890479467404e
info > meta_data 자동번역 서비스에서 집계하지는 않으나, 로그로 저장하는 값 Object N JSON Object String 변환 시, 1kb 이내 {“game” : “MLB”} or [{“key1”:“blabla”}]
text 번역 요청 내용 String Y ※ 문자열 Json 이스케이프 필요 “ \”등록\” 절차에 대한 문의”
from 번역 요청 언어 String Y “text”에 해당하는 언어 코드번역 지원 언어 및 Hive 언어코드 참고

※ async 번역은 번역 요청 내용에 대한 언어 자동감지를 지원하지 않습니다.

to 번역 응답 언어 String Y “,” 구분자로 분리 하여 여러 언어 요청 가능번역 지원 언어 및 Hive 언어코드 참고 1. (단일 언어 번역)“en”2. (다중 언어 번역)“en, fr, de”

Response

/api/translate/async/result/{uuid} 임

필드명 설명 타입 상세 예시
result 결과값 Object
result > code 결과 코드 Integer Response Code 참고 성공 시 ‘200’
result > msg 결과 메시지 String Response Code 참고 성공 시 ‘Success’
content 번역 결과값 Object
content > uuid 번역 결과 ID String UUID4 형식 ID
번역 상태 확인을 위한 ID
62fe5786-0bb8-4cd0-b51a-6d6f6bfe2bac
content > resultUrl 번역 상태 확인을 위한 URL String

Response Code

코드 텍스트 비고
200 “success” 성공
400 <> is Missing or
Incorrect request
실패 – 요청 파라미터 누락 or

실패 – 파싱 불가능 (JSON 오류)

401 Wrong Signature 실패 – 서명 키 이상
404 Unregistered app key 실패 – 등록되지 않은 앱 키
404 Unregistered job uuid 실패 – 등록되지 않은 job uuid
500 Internal Server Error (or Some message) 실패 – 서버 내부 오류

Request Example

Curl

Python

Java

Response Example

비동기 번역 결과 확인 API

비동기 번역 결과 확인 API는 비동기 번역 요청에 대한 번역 결과를 리턴합니다. 즉 요청과 응답을 구분하여 처리하는 비동기 API 중, 응답에 해당하는 API입니다.

Request URL

LIVE URL https://ats.withhive.com/api/translate/async/result/{uuid}
HTTP Method GET

Request Path

필드명 설명 타입 필수 여부 상세 예시
uuid 번역 결과 ID, 비동기 번역 요청에 대한 상태 응답 값 String Y 생성으로부터 ~Nday까지 확인 가능 5c8ded49-9ee2-412a-a0ab-a4018a0dc093

Request Header

필드명 설명 타입 필수 여부 상세 예시
Signature 인증을 위한 서명 값 String Y 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=

Response

필드명 설명 타입 상세 예시
result 결과값 배열 Object
result > code 결과 코드 Integer Response Code 참고 성공 시 ‘200’
result > msg 결과 메시지 String Response Code 참고 성공 시 ‘Success’
content 번역 결과 Object
content 번역 결과 Object
content > status 번역 상태값 Object 번역 상태 정보
content > status > code 번역 상태 코드 Integer 100 / 101 / 102 / 199
content > status > mag 번역 상태 메시지 String “completed(100)”/ “waiting(101)” / “processing(102)” / “failed(199)”
content > data 번역 결과값 Object ※ result>status>msg 값이
“waiting” / “processing” / “failed” 인 경우 필드 없음,
“completed”인 경우만 존재
content > data > translateMsg 번역값 배열 Array
content > data > translateMsg > translations 번역 텍스트 배열 Array 언어별 배열로 노출
content > data > translateMsg > translations > text 번역 텍스트 String Json 이스케이프 문자열 Inquiries about the \”Registration\” process
content > data > translateMsg > translations > to 번역 언어 국가 코드 String “en”

Response Code

코드 텍스트 비고
200 “success” 성공
400 <> is Missing or
Incorrect request
실패 – 요청 파라미터 누락 or

실패 – 파싱 불가능 (JSON 오류)

401 Wrong Signature 실패 – 서명 키 이상
404 Unregistered app key 실패 – 등록되지 않은 앱 키
404 Unregistered job uuid 실패 – 등록되지 않은 job uuid
500 Internal Server Error (or Some message) 실패 – 서버 내부 오류

Request Example

Curl

Python

Java

Response Example