Service Introduction

一、 Overview of services

LiveData Open Translation Platform aims at providing open services for a wide range of developers in the game industry.

二、 Apply for services

Translation API uses a complete flow and self-application model. Click on “Login” at the top of LiveData’s official website (https://www.ilivedata.com), and sign up following the instructions. Choose AI Live Translation Service and create an application. A pid and a service key will be sent to you.

You can also activate other services on the Management Console - Overview Page.

三、 Access Method

  • Request URL: Get it from “Livedata Console - Service Configuration”

  • HTTP request Header: Accept: application/json;charset=UTF-8

  • Request method: GET/POST

  • Request parameter

Parameter Essential Description
q Essential Please input source text. This text should be a UTF-8 encoded string with no more than 1024 characters.
source Essential Set language of the input text as one of the ISO 639-1 language codes listed in “Language Support”. API will always detect the language of the input text, or use the language set to translate if detection fails.
target Essential Set target language for translation as one of the ISO 639-1 language codes listed in “Language Support”
appId Essential The only identifier of the project or application.
profanity Optional Sensitive word filtering. Set as one of the following two options: off and censor. If this parameter is not set, it will be set as “off” by default. (1) off: don’t filter sensitive words. (2) censor: If there are sensitive words in translated texts, they will be replaced by asterisks (*) in translation results.
textType Optional Optional values are chat or mail. If not specified, “chat” is used by default.The “mail” mode is recommended if you want \t \n and space characters in the source text to remain unchanged in the translated texts, such as in-game letters.
timeStamp Essential The UTC timestamp of the request. Timestamps need to be formatted according to W3C standards, for example: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime).
  • Request signature:

When the user requests the Translation API, the request can be signed with the appId and secretKey. When the API receives the request with the signature information, it will verify the signature using the same algorithm, and if the signature is found to be inconsistent, the API will return 401 error to the user. If the API validation signature is consistent and the user corresponding to the appId has permission to operate the requested resource, the request succeeds, otherwise the API returns 401 error.

  • Request Header to send a signature via HTTP

Method: Add a header named Authorization in the request, whose value is the signature’s value. For example:

	Authorization: *****
  • Signature calculation method

    1. Canonicalized Query String:

      a. As signatures require uniqueness, including order, they need to be sorted by parameter name.

      b. The following rules are used to encode URLs for parameter names and values. For more information, see RFC 3986.

      * A-Z, a-z, 0-9, minus sign (-), underscore (_), full stop (.), and tilde (~) are not coded.
      * The other characters are encoded in the format %XY, where XY is the hexadecimal representation of the character corresponding to ASCII code and the letter is capitalized.For example, the double quotes (") correspond to the code %22
      * For extended UTF-8 characters, encoded in the format of %XY%ZA...
      * English spaces ( ) are to be encoded as %20 instead of the plus sign (+).
      

      c. Use the equal sign character (=) to separate the parameter name from the parameter value, even if the parameter value is null. Use arguments and value pairs separated from the character (&). Join parameters and their values to form a long string with no spaces between them. Spaces are allowed, but they must be URL encoded as %20. In the concatenated string, the period character (.) is not escaped. RFC 3986 treats period characters as unreserved characters and therefore does not URL encode them.

      d. Libraries that generally support URL encoding (such as java.net.URLEncoder in Java) are encoded according to the “application/x-www-form-urlencoded” MIME type rule. In practice, this method can be directly used for coding. Replace the plus sign (+) in the encoded string with %20, the asterisk (*) with %2A and %7E with tilde (~).

    2. Constructs the signed string StringToSign ("\n" stands for ASCII newline character):

          StringToSign = HTTPMethod + "\n" + 
                         HostHeaderInLowercase + "\n" + 
                         HTTPRequestURI + "\n" + 
                         CanonicalizedQueryString <got from previous step>
      

      The HTTPRequestURI is the absolute path to the request URI, without the request string. If the HTTPRequestURI is empty, also keep a forward slash (/)

    3. The hash-based message authentication code (HMAC) is created using the HMAC-SHA256 protocol and the signature is calculated.

      StringToSign as the signature string, secretKey as the secret key and SHA256 as the hash algorithm.

      For more information about HMAC, see HMAC: Hash Keys for Message Authentication (https://tools.ietf.org/html/rfc2104)。

    4. Converting the results of the previous step to a BASE64 string

    5. Put the BASE64 string into the Authorization of HTTP request Header

  • Example of signature

  1. Below is an example of appId & secretKey.

    appId=***
    secrectKey=*****
    
  2. Below is an example request.

     https://translate.ilivedata.com/api/v2/translate?source=en&target=zh-CN&q=hello%20world&appId=***&timeStamp=2015-09-23T04%3A55%3A07Z
    
  3. Generate StringToSign

     POST\n
     translate.ilivedata.com\n
     /api/v2/translate\n
     appId=***&q=hello%20world&source=en&target=zh-CN&timeStamp=2015-09-23T04%3A55%3A07Z
    
  4. Signatures from HMAC calculation

     *****
    
  • HTTP response:

Content-Type: application/json;charset=UTF-8

The result is in JSON format, please refer to the following example.