Getting started with Language Weaver

Note

All API examples use the Europe region by default, with the base URL https://api.languageweaver.com.
To use the US region, the base URL must be replaced with https://us.api.languageweaver.com.

Note

The GROUP_ID_X header may be included in a request to indicate the group context under which the request should be executed. When this header is present, the system applies the configuration and permissions associated with the specified group.
If the header is omitted, the request is processed using the caller’s default group.
Requests that reference a group to which the caller does not belong are rejected.

Note

It is recommended that each API request include a Trace-ID header containing a unique identifier (UUID). This identifier enables the system to trace and diagnose issues related to specific requests.
The Trace-ID header is described in the API specifications below and must be unique for every 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.