Getting started with Language Weaver

In order to create an asynchronous translation you should follow the next steps. We strongly suggest that when you make any API call, you include a request identifier in the header called Trace-ID which is a unique request identifier (UUID) so that if there are any issues with your API calls we will be able to trace them in our system. The Trace-ID header is described in the below API calls and should be unique per request.

Step 1: Authenticate

Before you are able to use any of the Language Weaver API calls you need to authenticate. By providing either a username and a password or a client id and a client secret. For username/password authentication happens using the /v4/token/user endpoint as described here. For clientid/clientsecret authentication happens using the /v4/token endpoint as described here. Authentication requests are handled using the OAuth 2.0 Authorization Framework.

Once you authenticate you will get back an access token. The Access Token will be added to the Authorization header of all API requests in the form "Authorization": "Bearer asd0eXAi..."

Step 2: Create a translation

  • Prerequisites
    When creating a translation you should know the source language, the target language and the model you want to translate on and also the input format of your input.

    If you don't already know the above info, in order to get all the source/target/model language combinations available you need to call the Get all language pairs endpoint as described in the Subscriptions section.

    If you don't know the source language for your input you can use auto as sourceLanguageId so that your source language gets automatically detected as described in the Text translation section or the File translation section.


Also, check what is the input format that matches your input type by checking the input formats section. Please note that for text translation only a subset of the input formats are available as described in the Asynchronous text translation section.

Note

Providing the wrong input format for your input will result in an erroneous translation.

  • Submit the translation call
    Perform the translation based on the input you are sending by calling either a text translation or a file translation.
    If the create translation API call is successful in the response JSON you will get back a unique id called requestId as described for both text translation and file translation sections. That requestId will be used to uniquely identify your translation in the subsequent API calls.

Step 3: Check the translation status

Use this call to check what is the status of your translation by providing your requestId as described in the check the translation status section
The translation status can be: INIT, TRANSLATING, DONE, FAILED. If the status is INIT or TRANSLATING you'll have to keep calling the check translation status endpoint until the translation has the status DONE or FAILED.

You need to set a sleep time between the subsequent calls made to the status endpoint /v4/mt/translations/async/{requestId} which should vary from 100 milliseconds for smaller inputs (up to 500 characters) to 500 milliseconds for larger inputs.
If the returned translation status is DONE then check the next step to see how to retrieve your translation.
If the returned translation status is FAILED then the translation process encountered some issues and the translation needs to be submitted again. If you get status FAILED more than two times in a row then the translation for that input will most likely not work and you should contact support.

Step 4: Retrieve the translated content

Use this call to retrieve the translated content of your request. For this you will need to call the /v4/mt/translations/async/{requestId}/content endpoint as described in both the text translation and the file translation sections.
For text translation you will get back a JSON and in the translation element you will get back the translated text.
For file translation you will get back the binary content of the translated file.



Note

Please take note that the existing API responses may be altered with the addition of new fields.