자동 번역 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. 서비스키(appKey), 비밀키 확인¶

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

2. Signature(서명) 확인¶

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

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

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

PythonJava

import hmac
import hashlib
import base64

app_key = "your_app_key"
secret_key = "your_secret_key"

# HMAC SHA-256 사용
signature_bytes = hmac.new(secret_key.encode('utf-8'), app_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 appKey = "your_app_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(appKey.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 > 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¶

CurlPythonJava

    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":{
                "app_key":"802890479467404e"
        },
        "text":"서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의",
        "to":"en,fr,de",
        "from" : "ko"
        }'

    import requests

    url = "https://ats.withhive.com/api/translate/sync"

    payload = {
            "info": {"app_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        \"app_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 > 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¶

필드명	설명	타입	상세	예시
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¶

CurlPythonJava

    curl --request POST \
    --url https://ats.withhive.com/api/translate/async \
    --header 'Content-Type: application/json' \
    --header 'Signature: pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=' \
    --data '{
        "info":{
                "app_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": {"app_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        \"app_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¶

CurlPythonJava

    curl --request GET 
    --url https://test-ats.withhive.com/api/translate/asyncresult/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2 
    --header 'Content-Type: application/json' 
    --header 'Signature: pczeZ91NijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c='

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"
                                            }
                                    ]
                            }
                    ]
            }
    }
}