skip to Main Content

This document describes the Lingo24 Business Translation API, which can be used to create and manage your document-based translation projects within the Lingo24 translation platform.

The API is designed around Representational State Transfer (REST) principles and allows clients to produce and access content using JSON (application/json) and/or XML (application/xml).

When interacting with the API, clients must specify which content type they will send using the Content-Type header. JSON is the default content type produced by the API. This can be overridden using the Accept header.
The API uses the OAuth Version 2 standard for authentication for all resources within the API. To be able to use the API you must sign-up for an account on our Developer Portal.

Within this portal you can create a Client ID and Client Secret for each application that will access the API.
As the Lingo24 Business Translation API builds on our core translation platform, any projects created via the API gain access to your existing translation assets and our graded quality level workflows.

Key Concepts

Adjusted team number

The API uses the OAuth Version 2 standards for authentication. For this, all requests to the
API, except requests to the authentication and authorization endpoints, must include the
Authentication header item (Authorization: Bearer <your_access_token>).

Translation Lifecycle

Interactions with the Lingo24 Business Translation API use REST resources that allow you to
follow a typical translation lifecycle:
• Create Project
• Upload File(s)
• Create Job(s)
• Confirm or Amend Project
• Receive Metrics for Job(s)
• Optionally, Edit Project
• Confirm Project
• Receive Target Files
• Download Target File(s)

Progression between stages is triggered and monitored by interacting with the resources within the REST API and using the status codes for projects and jobs.

To manage projects and jobs, upload files or view metrics, the client should use the standard REST pattern of GET, PUT, POST and DELETE commands against the resources of the same name.

As you build a project each job is analyzed and priced. At this stage both the file metrics and overall price are available, allowing the client to DELETE either individual jobs or the entire project.

Having reviewed the jobs in the project, a client can either choose to accept the project and start the translation (changing the project status to IN_PROGRESS) or save a quote for review (changing the project status to QUOTED).

A typical quote is valid for 15 days, although this will depend on individual terms and conditions. A quoted project can be accepted by changing the project status to IN_PROGRESS within that timeframe.

Changing the status of the project is achieved by using a PUT command. It should be noted that once a project is IN_PROGRESS, amendments and cancellations are subject to the standard Lingo24 terms and conditions.

At each stage of the lifecycle, we can trigger a callback or you can poll for updates until the job is complete. This is discussed in the Callback section.

Callbacks

When creating an API account with Lingo24, you can set an optional default callback URL for any projects or jobs created. If set, Lingo24 will post any updates about the project or job as they happen.

Callback notifications are sent when:
• A job has been priced and has metrics available
• A job is complete and has target files available for review
• A project is complete

We will make up to three attempts to submit data to the callback URL. If the end point is not reachable, we will send an email alert and you will need to make a request directly against our API.

Where required, the default callback URL can be overridden for a specific project or job when creating the resource. Callbacks are modelled as PUT requests and will contain in the contents the JSON data the payloads associated with that resource, and in the header, the number of attempts made to deliver to the callback URL.

To receive a callback you must be able to process these requests:
• PUT /project/{projectId} HTTP/1.1
• PUT /job/{jobId} HTTP/1.1

Pagination

To enable end clients to limit the amount of data returned and support pagination, the API
supports two general parameters on GET requests; limit and offset.

limit
If present as a query parameter while a GET request is being made on a collection resource (/job, /project etc) the number of returned entities is limited to the value of the parameter:
• the value must be greater or equal to 0
• if the value is 0, all the entities are returned
• in absence of this parameter, a default value of 10 is used

offset
If present as a query parameter while a GET request is being made on a collection
resource (/job, /project etc), the entity list returned is offset by the specified value:the
value must be greater or equal to 0
• the value must be greater or equal to 0
• in absence of this parameter, a default value of 0 is used

Payloads

Locale

• id: the object’s ID
• language: the ISO 639-1 language code
• country: ISO 3166 A2 country code

Service

• id: the object’s ID
• name: the translation service’s name
• description: the translation service’s description

Domain

• id: the object’s ID
• name: the translation domain name

Project

• id: the object’s ID
• created: the UNIX timestamp in seconds when the project was created in Ease
• name: the project’s name
• projectStatus: the project’s status

File

• id: the object’s ID
• name: the file’s name.
• type: one of SOURCE, TARGET, AUXILIARY, QUOTE, INVOICE

Job

• id: the object’s ID
• projectId: the projects object’s ID
• jobStatus: the current job’s status
• serviceId: the translation service id
• sourceFileId: the job’s source file ID
• sourceLocale: the BCP 47 code for the source locale
• targetFileId: the job’s target file ID
• sourceLocaleId: the source locale ID
• targetLocaleId: the target locale ID

Status Codes

Each project and job goes through a series of statuses before delivery. At any time when you request the contents of either resources, it will be in one of the states outlined below.

Status codes are also used to allow clients to approve or cancel projects for translation as well as a store a quote for later use. For example, to accept a quote and start a project a PUT request is required to be sent to the Project resource changing the status of the existing project from QUOTED to IN_PROGRESS.

Project

Each project and job goes through a series of statuses before delivery. At any time when you request the contents of either resources, it will be in one of the states outlined below.
• CREATED – the project has been created in our system, ready for configuration. In this status you can manipulate jobs.
• QUOTED – this is an optional status. Updating a project to this status saves a quote in our system. In this status you cannot further manipulate the project. A typical quote is valid for 15 days, although this will depend on individual terms and conditions.
• IN_PROGRESS – a project will be in this status when it has been accepted by the client. Changing it to this status triggers Lingo24 to start work on your project.
• CANCELLED – this status is when a project has been cancelled by the client. Changing the project to this status tells Lingo24 to cancel the project. Project cancellations are covered by our standard terms and conditions.
• FINISHED – projects move to this status once all of the project’s jobs have been completed.

Job

• NEW – the job has been created in our system and is waiting to be analyzed.
• ANALYZING – the job is being analyzed. Switching to this status from NEW is done automatically.
• QUOTED – the job has been analyzed and has both metrics and price available.
• IN_PROGRESS – the job is currently underway at Lingo24.
• TRANSLATED – the job is now finished, with the target files available for collection via the File resource.
• CANCELLED – the job has been cancelled.

Resources

OAuth2 resource

POST /oauth2/access HTTP/1.1
Consumes
Consumes only application/x-www-form-urlencoded, as per the OAuth v2
specifications.

Depending on the requested grant type, the expected fields are the following:
• grant_type: the grant type
• client_secret: the client application’s secret
• client_id: the client application’s ID.

For a grant type of authorizatio_code:grant_type: the grant type:
• code: the authorization code received from the authorization page
• redirect_uri: client uri where to redirect the client
For a grant type of refresh_token:
• refresh_token: the refresh token, if the grant_type is refresh_token

Produces
An OAuth2 object with the following structure:
• access_token: the access token to be used in every API request
• expires_in: the seconds until the current access token expires
• refresh_token: the refresh token
• token_type: the token type. Currently only Bearer is used

HTTP status codes
• 200 OK

Locales

GET /locale HTTP/1.1
Returns a list of locales.

HTTP status codes
• 200 OK

GET/locale/{id} HTTP/1.1
Returns the service level object with the specified id

HTTP status codes
• 200 OK
• 404 Not found: if the locale with the specified ID was not found

Service Level

GET /service HTTP/1.1
Returns a list of service levels.

HTTP status codes
• 200 OK

GET/service/{id} HTTP/1.1
Returns the service level object with the specified id

HTTP status codes
• 200 OK
• 404 Not found: if the service level with the specified key was not found

Translation Domains

GET /domain HTTP/1.1
Get a list of Lingo24’s available translation domains.

HTTP status codes
• 200 OK

GET /domains/{id} HTTP/1.1
Get a specific translation domain for use within a translation job.

HTTP status codes
• 200 OK

Projects and Jobs

GET /project HTTP/1.1
Returns the list of projects.

HTTP status codes
• 200 OK

GET /project/{id} HTTP/1.1
Returns the project with the specified ID.

HTTP status codes
• 200 OK
• 404 Not found: if the project with the specified id was not found.

POST /project HTTP/1.1
• Create a new project. The name is mandatory when sending the project
object. Returns the created project with the new ID and project status fields
filled in.

HTTP status codes
• 200 OK
• 400 Bad request.

PUT /project/{id} HTTP/1.1
• Edit an existing object. The name is mandatory when sending the project
object. Returns the modified project object

HTTP status codes
• 200 OK
• 404 Not found: if the project with the specified id was not found
DELETE /project/{id} HTTP/1.1
• Deletes a project

HTTP status codes
• 200 OK
• 404 Not found: if the project with the specified id was not found

Jobs

GET /job HTTP/1.1
Returns the list of all the jobs for the client. Adding a projectId query parameter allows the client to access jobs within a specific project.

HTTP status codes
• 200 OK

GET /job/{id} HTTP/1.1
Returns the job with the specified ID.

HTTP status codes
• 200 OK
• 404 Not found: if the job with the specified id was not found

GET /job/{id}/metrics HTTP/1.1
Returns the metrics for the job with the specified ID

HTTP status codes
• 200 OK
• 204 No content: if there are no metrics
• 404 Not found: if the job with the specified id was not found

GET /job/{id}/price HTTP/1.1
Returns the price for the job with the specified ID.

HTTP status codes
• 200 OK
• 204 No content: if there are no metrics
• 404 Not found: if the job with the specified id was not found

POST /job HTTP/1.1
Creates a new job, returning the created job object in the response. The mandatory fields are: projectId, sourceFileId, sourceLocale, targetLocale and serviceLevel.

HTTP status codes
• 200 OK
• 400 Bad request

PUT /job/{id} HTTP/1.1
Edits an existing object

HTTP status codes
• 200 OK
• 404 Not found: if the job with the specified id was not found

DELETE /job/{id} HTTP/1.1
Deletes a job

HTTP status codes
• 200 OK
• 404 Not found: if the job with the specified id was not found

Files

GET /file HTTP/1.1
Returns the list of files.

HTTP status codes
• 200 OK
• 404 Not found: if the file with the specified id was not found

GET /file/{id} HTTP/1.1
Returns the file with the specified ID.

HTTP status codes
• 200 OK
• 404 Not found: if the file with the specified id was not found

GET /file/{id}/content
Returns the file’s content.

HTTP status codes
• 200 OK
• 400 Bad request

DELETE /file/{id} HTTP/1.1
Delete a file

HTTP status codes
• 200 OK
• 404 Not found: if the file with the specified id was not found