Automatic translation API

The automatic translation API is an API that allows you to easily set the translation type and translator. It supports both real-time synchronous translation and asynchronous translation, providing a flexible translation environment.

The types of automatic translation APIs can be broadly categorized into synchronous translation APIs that allow real-time translation and asynchronous translation request APIs and asynchronous translation result checking APIs that do not allow real-time translation.

Notes¶

Supported text formats¶

The text formats supported by the synchronous translation API and the asynchronous translation API are as follows.

Synchronous Translation API: Supports plain text and HTML format
Asynchronous Translation API: Supports Markdown format

Project matching method¶

The automatic translation API provides two ways to match translation services for each game project registered in the app center.

Automatic translation service and 1:1 matching: Register the services used for each project
When calling a single automatic translation service, enter the project ID for matching: Add each project ID to the API call

Translation supported languages¶

The translation languages supported by Hive are a total of 16, as listed below.

Language	Language Notation	Hive Language Code
Korean	한국어	ko
English	English	en
Japanese	日本語	ja
Simplified Chinese	简体中文	zh-hans
Traditional Chinese	繁體中文	zh-hant
French	Français	fr
German	Deutsch	de
Russian	русский	ru
Spanish	Español	es
Portuguese	Português	pt
Indonesian	Bahasa Indonesia	id
Vietnamese	tiếng Việt	vi
Thai	ไทย	th
Italian	Italiano	it
Turkish	Türkçe	tr
Arabic	العربية	ar

Prerequisites¶

The prerequisites for using the automatic translation API are as follows.

1. Check service key and secret key¶

Hive Console > AI Services > Automatic Translation > Automatic Translation System > Service Management to register the service.
Check the service key and secret key for the product.

2. Signature verification¶

The API server generates a Signature using the service key and secret key.

Select key management in the Hive console > AI services > Automatic translation > Automatic translation system > Service management to check the generated signature. An example of the generated signature code is as follows.

The signature is the Base64 value encoded with HmacSHA256 using the service key and secret key.

PythonJava

import hmac
import hashlib
import base64

service_key = "your_service_key"
secret_key = "your_secret_key"

# Using 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')

# Add signature to HTTP request
# ...

public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
String serviceKey = "your_service_key";
String secretKey = "your_secret_key";

// Using HMAC SHA-256
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(secretKeySpec);

// Signature generation
byte[] signatureBytes = sha256_HMAC.doFinal(serviceKey.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(signatureBytes);

// Add signature to HTTP request
// ...
}

Sync translation API¶

Processes translation requests and results in real-time synchronous mode with a single API request and response. Since the translation result is provided directly in the API response, there is no API available to check the translation result.

This is a synchronous translation text type that supports plain text and HTML text formats that do not require pre/post-processing.

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¶

Field Name	Description	Type	Required	Details	Example
project_id	App Center Project ID	String	N	1. If there is a value: Aggregate by project ID 2. When there is no value: Aggregate as "None"	com.com2us.project1

Request header¶

Field Name	Description	Type	Required	Details	Example
Signature	Signature value for authentication	String	Y	Value encoded with HmacSHA256 using the secret key of the service key	IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=

Request body¶

Field Name	Description	Type	Required	Details	Example
info	Service key information object	Object	Y
info > service_key	Service key value	String	Y		802890479467404e
info > meta_data	Values that are not aggregated in the automatic translation service but are stored in logs	Object	N	When converting to JSON Object String, within 1kb	{“game” : “MLB”} or [{“key1”:“blabla”}]
text	Translation request content	String	Y	※ String Json escape required	“ \”Inquiry about the registration procedure\”
from	Translation request language	String	Y	Language code corresponding to “text” Translation support languages and Hive language codes reference ※ Entering “auto” will automatically detect (lowercase)	1. (Automatic detection) “auto” 2. (Korean) “ko”
to	Translation response language	String	Y	Multiple languages can be requested by separating with “,” Translation support languages and Hive language codes reference	1. (Single language translation) “en” 2. (Multi-language translation)“en, fr, de"

Response¶

Field Name	Description	Type	Details	Example
result	Result value	Object
result > code	Result code	Integer	Refer to Response Code	'200' on success
result > msg	Result message	String	Refer to Response Code	'Success' on success
content	Translation result	Object
content > data > translateMsg	Array of translation values	Array
content > data > translateMsg > detectedLanguage	Value related to input language	Object	※ Exists if "Translation request language (from)" is "auto"
content > data > translateMsg > detectedLanguage > language	Detected value of input language	String	Refer to supported translation languages and Hive language codes
content > data > translateMsg > detectedLanguage > score	Input language detection score (the closer to 1, the more accurate)	Number (Float)		1.0
content > data > translateMsg > translations	Array of translated texts	Array	Displayed as an array by language
content > data > translateMsg > translations > text	Translated text	String	Json escaped string	Inquiries about the \"Registration\" process
content > data > translateMsg > translations > to	Translation language country code	String		"en"

Response code¶

Code	Text	Remarks
200	"success"	Success
400	<> is Missing or Incorrect request	Failure * Missing request parameter or Failure * Unable to parse (JSON error)
401	Wrong Signature	Failure * Signature key issue
404	Unregistered app key	Failure * Unregistered service key
404	Unregistered job uuid	Failure * Unregistered job uuid
500	Internal Server Error (or Some message)	Failure * Internal server error

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":{
                "service_key":"802890479467404e"
        },
        "text":"Request for the procedure for creating a server account application and managing multilingual content",
        "to":"en,fr,de",
        "from" : "ko"
        }'

    import requests

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

    payload = {
            "info": {"service_key": "802890479467404e"},
            "text": "Inquiry about the multilingual content management process for server account application and account creation",
            "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\":\"Server account application account creation multilingual content management procedure inquiry\",\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"
                }]
            }]
        }
    }
  }

Asynchronous translation request API¶

The asynchronous translation API processes translation requests and responses separately through two APIs. There are two main APIs: the 'Asynchronous Translation Request API' for requests and the 'Asynchronous Translation Result Check API' for responses.

This is a translation text type for the body, supporting markdown text format that requires pre/post-processing.

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¶

Field Name	Description	Type	Required	Details	Example
project_id	App Center Project ID	String	Y	1. When there is a value: Aggregate by project ID 2. When there is no value: Aggregate as "None"	com.com2us.project1

Request header¶

Field Name	Description	Type	Required	Details	Example
Signature	Signature value for authentication	String	Y	Value encoded with HmacSHA256 using the secret key of the service key	pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=

Request body¶

Field Name	Description	Type	Required	Details	Example
info	Service key information object	Object	Y
info > service_key	Service key value	String	Y		802890479467404e
info > meta_data	Value that is not aggregated in the automatic translation service but is saved in logs	Object	N	When converting to JSON Object String, within 1kb	{“game” : “MLB”} or [{“key1”:“blabla”}]
text	Content of the translation request	String	Y	※ String JSON escape required	“ \”Inquiry about the registration procedure”
from	Language of the translation request	String	Y	Language code corresponding to “text” Translation support languages and Hive language codes reference ※ Async translation does not support automatic language detection for the translation request content.
to	Translation response language	String	Y	Multiple language requests are possible by separating with a “,” Translation support languages and Hive language code reference	1. (Single language translation) “en” 2. (Multilingual Translation) “en, fr, de"

Response¶

Field Name	Description	Type	Details	Example
result	Result value	Object
result > code	Result code	Integer	Refer to Response Code	'200' on success
result > msg	Result message	String	Refer to Response Code	'Success' on success
content	Translation result value	Object
content > uuid	Translation result ID	String	UUID4 format ID ID for checking translation status	62fe5786-0bb8-4cd0-b51a-6d6f6bfe2bac
content > resultUrl	URL for checking translation status	String	/api/translate/async/result/{uuid} is

Response code¶

Code	Text	Remarks
200	"success"	Success
400	<> is Missing or Incorrect request	Failure * Missing request parameter or Failure * Parsing impossible (JSON error)
401	Wrong Signature	Failure * Signature key abnormal
404	Unregistered app key	Failure * Unregistered service key
404	Unregistered job uuid	Failure * Unregistered job uuid
500	Internal Server Error (or Some message)	Failure * Internal server error

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":{
                "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"
    }
 }

Asynchronous translation result check API¶

The Asynchronous Translation Result Check API returns the translation results for asynchronous translation requests. In other words, it is the API corresponding to the response among asynchronous APIs that handle requests and responses separately.

Request URL¶

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

Request path¶

Field Name	Description	Type	Required	Details	Example
uuid	Translation result ID, status response value for asynchronous translation requests	String	Y	Can be checked from creation to ~Nday	5c8ded49-9ee2-412a-a0ab-a4018a0dc093

Request header¶

Field Name	Description	Type	Required	Details	Example
Signature	Signature value for authentication	String	Y	Value encoded with HmacSHA256 using the secret key of the service key	pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=

Response¶

Field Name	Description	Type	Details	Example
result	Array of results	Object
result > code	Result code	Integer	Refer to Response Code	'200' on success
result > msg	Result message	String	Refer to Response Code	'Success' on success
content	Translation result	Object
content	Translation result	Object
content > status	Translation status value	Object	Translation status information
content > status > code	Translation status code	Integer		100 / 101 / 102 / 199
content > status > msg	Translation status message	String		“completed(100)”/ “waiting(101)” / “processing(102)” / “failed(199)”
content > data	Translation result value	Object	※ If the result>status>msg value is “waiting” / “processing” / “failed” there will be no field, only exists when “completed”
content > data > translateMsg	Array of translation values	Array
content > data > translateMsg > translations	Array of translation texts	Array	Displayed as an array by language
content > data > translateMsg > translations > text	Translation text	String	Json escaped string	Inquiries about the \"Registration\" process
content > data > translateMsg > translations > to	Translation language country code	String		"en"

Response code¶

Code	Text	Remarks
200	"success"	Success
400	<> is Missing or Incorrect request	Failure * Missing request parameter or Failure * Parsing impossible (JSON error)
401	Wrong Signature	Failure * Signature key abnormal
404	Unregistered app key	Failure * Unregistered service key
404	Unregistered job uuid	Failure * Unregistered job uuid
500	Internal Server Error (or Some message)	Failure * Internal server error

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