Lengoo Connect API is a RESTful HTTP API that provides a way to programmatically interface with Lengoo's translation process. It allows creating translation jobs and getting notified when they're completed and ready for delivery.

This API is available to Customers who have commercial agreements in place that allow for translation Jobs to be automatically approved.

The basic workflow consists of providing source texts, defining the Job parameters, and then either polling the Job endpoint or waiting for a webhook to fire when the translation is done.

You can add arbitrary metadata to Files and Jobs too. This is a way to store any information you might need for your integration. For example, you can use it to store the information related to the pages or blocks in your CMS that a File or a Job is about. Additionally files have an additional field for storing reference IDs to enable easy processing. That way, you don't need to run a database on your side. No particular format is enforced for that metadata.

Every HTTP call to the API requires OAuth2 authentication.

Invalid credentials result in an HTTP 401 Forbidden error response.

A client ID and secret is required. To request for client ID and secret or decommision one reach out to your account manager or sales rep.

Base64 encode the client ID and secret using command.

echo -n clientid:clientsecret | base64

Copy value and then pass through Basic Authentication.

Note that the scope of the request should be connect_api.

  curl --request POST \
    --url https://id.lengoo.com/oauth2/aus2i12rp7MwhLcLB417/v1/token \
    --header 'accept: application/json' \
    --header 'authorization: Basic MG9hY...' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'grant_type=client_credentials&scope=connect_api'

Add the Token to the Authorization header on every request made. The Authorization type is the Bearer Token and the value is the Token generated from the earlier request.

Example:

  curl --location --request GET '{baseUrl}/api/jobs' \
  --header 'authorization: Bearer eyJra...' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Spring Collection Landing Page",
    "description": "Translation of the Spring Collection Landing Page on our marketing website",
    "sourceLanguage": "de-AT",
    "targetLanguages": ["en-US"],
    "files": [
        {
            "id": "d7e9f332-afe2-4005-aa52-8cfd361b391c"
        }
    ]
  }'

In order to start a translation Job, it's necessary to have source texts to translate. Currently there's only one way to provide them: as files.

Upload them using the Files endpoint. That will give each file a unique URI you can use when creating a Job.

A translation Job is created by POSTing to the Jobs endpoint with the basic configuration of the Job. Afterwards, it's possible to add source files to the Job's by first uploading those files, then linking them.

The job doesn't actually start until you POST a translation request.

Once a Job is submitted for translation, it should be automatically accepted if all the details are valid. If they're not, the API returns an error 400 with more information.

In rare cases, a Job might be rejected after it's been accepted. The best way to deal with that is by getting in touch with your Lengoo Project Manager. In the future we expect to support full programmatic rejection / resubmission.

When a translation job is done or a partial delivery of a translation has occured, you can get notified about the status of the job if you have the webhook registered.

In the case where you have registered for a job.done webhook event with an active secured URL, you will get a request notification of the job payload when the job is completed via the url provided when you registered for the event.

If you have registered for a job.partial webhook event with an active secured URL, you will get a request notification of the job payload when the job has received a new translation via the registered url for the event

The secret you provide will be used to encode the payload in the X-Signature-Hmac-Sha256 header which will be in the notification request you will recieve.

The Lengoo Connect API is also available in a sandbox environment for development purposes, which doesn't trigger real translations.

Files hold the texts that are subject to translation. They can be used as input and downloaded as output after translations are done.

Jobs represent the discrete translation orders that a Customer can place.

Available language combinations for translation Jobs