자동 번역 API
자동 번역 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. 서비스키, 비밀키 확인¶
- Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 서비스를 등록합니다.
- 제품에 대한 서비스키와 비밀키를 확인합니다.
2. Signature(서명) 확인¶
API 서버의 백오피스에서는 서비스키와 비밀키를 사용하여 Signature(서명)을 생성합니다.
Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 키 관리 선택하여 생성된 서명을 확인합니다. 생성된 서명 코드 예시는 아래와 같습니다.
※ 서명은 서비스키와 암호키를 사용하여 HmacSHA256 인코딩한 Base64 값입니다.
import hmac
import hashlib
import base64
service_key = "your_service_key"
secret_key = "your_secret_key"
# HMAC SHA-256 사용
signature_bytes = hmac.new(secret_key.encode('utf-8'), service_key.encode('utf-8'), hashlib.sha256).digest()
signature = base64.b64encode(signature_bytes).decode('utf-8')
# HTTP 요청에 서명 추가
# ...
public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
String serviceKey = "your_service_key";
String secretKey = "your_secret_key";
// HMAC SHA-256 사용
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(secretKeySpec);
// 서명 생성
byte[] signatureBytes = sha256_HMAC.doFinal(serviceKey.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(signatureBytes);
// HTTP 요청에 서명 추가
// ...
}
동기 번역 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 > service_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 --request POST \
--url https://ats.withhive.com/api/translate/sync \
--header 'Content-Type: application/json' \
--header 'Signature: IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=' \
--data '{
"info":{
"service_key":"802890479467404e"
},
"text":"서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의",
"to":"en,fr,de",
"from" : "ko"
}'
import requests
url = "https://ats.withhive.com/api/translate/sync"
payload = {
"info": {"service_key": "802890479467404e"},
"text": "서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의",
"to": "en,fr,de",
"from": "ko"
}
headers = {
"Content-Type": "application/json",
"Signature": "IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY="
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"info\":{\n \"service_key\":\"802890479467404e\"\n },\n \"text\":\"서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의\",\n \"to\":\"en,fr,de\",\n \"from\" : \"ko\"\n}");
Request request = new Request.Builder()
.url("https://ats.withhive.com/api/translate/sync")
.post(body)
.addHeader("Content-Type", "application/json")
.addHeader("Signature", "IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=")
.build();
Response response = client.newCall(request).execute();
Response example¶
{
"result" : {
"code" : 200,
"msg" : "Success"
},
"content" : {
"data" : {
"translateMsg":[{
"detectedLanguage":{
"language":"ko",
"score":-1.0
},
"translations":[{
"text":"Server Account Application Create an account Inquiries about the multilingual content management process",
"to":"en"
},
{
"text":"Demande de compte serveur Créer un compte Demandes de renseignements sur le processus de gestion de contenu multilingue",
"to":"fr"
},
{
"text":"Server-Konto-Anwendung Konto erstellen Anfragen zum mehrsprachigen Content-Management-Prozess",
"to":"de"
}]
}]
}
}
}
비동기 번역 요청 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 > service_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¶
| 필드명 | 설명 | 타입 | 상세 | 예시 |
|---|---|---|---|---|
| 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 | /api/translate/async/result/{uuid} 임 |
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 --request POST \
--url https://ats.withhive.com/api/translate/async \
--header 'Content-Type: application/json' \
--header 'Signature: pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=' \
--data '{
"info":{
"service_key":"815e3d8d6e7443ba"
},
"text":"# Markdown Cheat Sheet ......",
"to":"ko,ja,zh-hant",
"from":"en"
}'
import requests
url = "https://ats.withhive.com/api/translate/async"
payload = {
"info": {"service_key": "815e3d8d6e7443ba"},
"text": "# Markdown Cheat Sheet ......",
"to": "ko,ja,zh-hant",
"from": "en"
}
headers = {
"Content-Type": "application/json",
"Signature": "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c="
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"info\":{\n \"service_key\":\"815e3d8d6e7443ba\"\n },\n\t\"text\":\"# Markdown Cheat Sheet
......\",\n \"to\":\"ko,ja,zh-hant\",\n\t\t\"from\":\"en\"\n}\n");
Request request = new Request.Builder()
.url("https://ats.withhive.com/api/translate/async")
.post(body)
.addHeader("Content-Type", "application/json")
.addHeader("Signature", "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=")
.build();
Response response = client.newCall(request).execute();
Response example¶
{
"result": {
"code": 200,
"msg": "Success"
},
"content": {
"uuid": "d2a36ba1-1bb3-43aa-ac57-46576d27eb37",
"resultUrl": "https://test-ats.withhive.com/api/translate/async/result/d2a36ba1-1bb3-43aa-ac57-46576d27eb37"
}
}
비동기 번역 결과 확인 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¶
import requests
url = "https://ats.withhive.com/api/translate/async/result/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2"
headers = {
"Content-Type": "application/json",
"Signature": "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c="
}
response = requests.request("GET", url, headers=headers)
print(response.text)
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://ats.withhive.com/api/translate/async/result/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2")
.get()
.addHeader("Content-Type", "application/json")
.addHeader("Signature", "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=")
.build();
Response response = client.newCall(request).execute();
Response example¶
{
"result": {
"code": 200,
"msg": "Success"
},
"content": {
"status": {
"code": 100,
"msg": "completed"
},
"data": {
"translateMsg": [
{
"translations": [
{
"text": "# Markdown 치트 시트\r\n\r\n......",
"to": "ko"
},
{
"text": "# Markdownチートシート\r\n\r\n......",
"to": "ja"
},
{
"text": "# Markdown 備忘單\r\n\r\n......",
"to": "zh-hant"
}
]
}
]
}
}
}