Using REST for Near Real-Time Translations

The Language Studio™ REST API is designed to translate chat and similar short text strings in near real-time. For longer text strings and other document formats, the Language Studio™ Java or .NET APIs should be used.


This document describes how to use the common features of the Language Studio™ Enterprise REST API V3.x using the RESTful calling style. The result of a request to the Language Studio™ REST API is a simple JSON object.


Identifying your application to Language Studio™

Your application needs to identify itself every time it sends a request to the Language Studio™ REST API, by including an API Key with each request. An API key is a unique identifier that is generated for you by your account manager and can be provided on request. The API key is part of the authorization requirements that are used in conjunction with Account Number. All data in Language Studio™ is transmitted encoded in UTF-8.

To acquire an API key, follow the below steps:

  1. Log into your Language Studio™ Enterprise V3.x account at http://www.languagestudio.com or your own server URL.
  2. Select My Profile from the left side menu.
  3. If this is the first time you have required an API key or you wish to change API key, click on the Generate API Key button.
  4. Copy the API key from the display at the bottom of the form.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs. The API key is safe for embedding in URLs; it doesn’t need any encoding.


Translate Text

You can translate text from one language to another language by sending an HTTP GET request to its URI. The URI for a request has the following format:


http://[ServerURL]/AORESTAPI/V3.jsp?key=INSERT-YOUR-KEY&accountnumber=1234&domaincode=1234&sourcetext=Das%20ist%20ein%20Test.


Four query parameters are required with each translation request:


API Key Use the key query parameter to identify your application.
Account Number Use the accountno query parameter to identify your account number.
Domain Code Use the domaincode query parameter to specify the domain code of the custom engine to be used for this translation.
Source Text Use the sourcetext query parameter to specify the text that you wish to translate.

The following five query parameters are optional:

Input Type Use the inputtype query parameter to specify the type of text being submitted. The default if not specified is plaintext.
Debug Logging Use the debuglog query parameter to specify whether to return debug information. Default = 0 (false)
Output Source Text Use the outputsourcetext query parameter to specify whether to return the original source text in the output. Default = 0 (false)
Output Confidence Use the outputconfidence query parameter to specify whether to return a confidence score in the output. Default = 0 (false)
Output Origin Use the outputorgin query parameter to specify whether to return the origin (cache or engine) of the translation output. Default = 0 (false)

The URL for the GET, including parameters, must be less than 2K characters.


Note: You can also use POST to invoke the API if you want to send more data in a single request. The sourcetext parameter in the POST body must be less than 5K characters.


Here is an example that specifies the domain code 1234 and the source text “Das ist ein test” as query parameter:

GET https://[ServerURL]/AORESTAPI/V3.jsp?key=INSERT-YOUR-KEY&accountnumber=1234&domaincode=1234&sourcetext=Das%20ist%20ein%20test.


Note: http or https can both be used depending on whether a SSL certificate has been installed on your server.

If the request succeeds, the server responds with a 200 OK HTTP status code and the data properties:


JSON

200 OK
{
    "data": {
        "translations": [
            {
                "translatedText": "This is a test"
            }
        ]
    }
}


In this example, the response is simply the 'translation' field, with the translation.


Here is an another example that includes the source text in the output:


GET https://[ServerURL]/AORESTAPI/V3.jsp?key=INSERT-YOUR-KEY&accountnumber=1234&domaincode=1234&sourcetext=Das%20ist%20ein%20Test.&outputsourcetext=1


If the request succeeds, the server responds with a 200 OK HTTP status code and the data properties:


JSON

200 OK
{
    "data": {
        "translations": [
            {
                "translatedText": "This is a test",
                "sourceText": "Das ist ein test"
            }
        ]
    }
}


Server Responses Codes and Errors

If the request succeeds, the server responds with a 200 OK HTTP status code and the data properties. If the request fails, the server responds with an appropriate HTTP status code and the error text in the data properties.


Response Codes:

200 OK
401 Unauthorized
412 Precondition Failed
450 Invalid domaincode
451 Invalid inputtype
452 Invalid sourcetext
500 Internal Server Error


Example 1

JSON

401 Unauthorized
{
    "error": {
        "code": 401,
        "message": "Invalid accountno or key"
    }
}


Example 2

JSON

500 Internal Server Error
{
    "error": {
        "code": 500,
        "message": "Pre-process: Error occured at Step1-TUTagDocument."
    }
}