Tilde MT API integration
Integrate machine translation into your application or website with Tilde MT API.
- Translate text and files effortlessly: Tilde MT API supports plaintext as well as most common office files, images, web and interchange formats.
- Customize translations with Glossaries: Ensure translation accuracy for industry-specific terms or brand names. Create private glossaries on Tilde MT platform and use them to improve translations.
Explore the Swagger API specification: https://translate.tilde.ai/api-description
Try the .NET library: Github repository
See the list of supported languages: Language support
Service endpoint
A service endpoint is a base URL that specifies the network address of an API service. Tilde MT service has the following service endpoint and all URIs below are relative to this service endpoint:
https://translate.tilde.ai/api/
Text translation is accessible at: https://translate.tilde.ai/api/translate/text
File translation is accessible at: https://translate.tilde.ai/api/translate/file
Authentication
The API uses an access key for authentication. Log into the Tilde MT platform, and create a new access key https://translate.tilde.ai/access-keys. Read more about access keys: Create an access key on Tilde MT platform.
You must include an X-Api-Key header in your request with your unique key.
Header Example:
X-Api-Key: YOUR_API_KEY
Replace YOUR_API_KEY with your actual access key. Requests without a valid access key in the X-Api-Key header will be rejected.
Translate text
To translate text, you'll make a POST request to the /translate/text endpoint. This endpoint translates one or more text segments from a source language to a target language. The request body must be in JSON format (application/json).
- HTTP Request
- cURL
- Node.js
POST {BASE_URL}/api/translate/text HTTP/2
Host: {host_URL}
accept: text/plain
content-length: 141
content-type: application/json
x-api-key: YOUR_API_KEY
{
"srcLang": "en",
"trgLang": "de",
"domain": "general",
"text": [
"Hello, world!",
"How are you?"
],
"termCollections": []
}
curl -X 'POST' \
'{BASE_URL}/api/translate/text' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: YOUR_API_KEY' \
-d '{
"srcLang": "en",
"trgLang": "de",
"domain": "general",
"text": [
"Hello, world!",
"How are you?"
],
"termCollections": []
}'
import axios from 'axios';
async function translateText() {
const url = '{BASE_URL}/api/translate/text';
const headers = {
'Content-Type': 'application/json',
'X-API-KEY': 'YOUR_API_KEY',
'accept': 'text/plain',
};
const body = {
srcLang: 'en',
trgLang: 'de',
domain: 'general',
text: ['Hello, world!', 'How are you?'],
termCollections: [],
};
try {
const response = await axios.post(url, body, { headers });
console.log('Status:', response.status);
console.log('Body:', response.data);
} catch (error) {
console.error('Error making the request:', error.response ? error.response.data : error.message);
}
}
translateText();
{
"domain": "General",
"translations": [
{
"translation": "Hallo Welt!"
},
{
"translation": "Wie geht es dir?"
}
],
"detectedLanguage": null
}
Request parameters
The main object in your request body should contain the following fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | Array of Strings | Yes | An array of text segments to be translated. Each string is treated as an individual segment. |
srcLang | String (max 10 chars) | No | The language code of the source text (e.g., en, lv). If omitted, the API attempts to auto-detect the language. |
trgLang | String (max 10 chars) | Yes | The language code for the desired translation (e.g., fr, de). |
domain | String (max 200 chars) | No | Specifies a subject area or domain for the translation to use a domain-specific translation engine. Available domains are general and general ai with custom domains for private engines. |
engineId | String (UUID) | No | The unique identifier of a specific custom translation engine to use. |
termCollections | Array of Strings (UUID) | No | A list of unique identifiers for term collections (glossaries) to be applied during translation. If a glossary is selected when creating an access key on the platform or set as default glossary this field can be left empty. |
Responses
200 - OK
{
"domain": "string",
"translations": [
{
"translation": "string"
}
],
"detectedLanguage": "string"
}
400 - Missing or incorrect parameters
This error occurs when a required parameter of the request is missing or one of the specified parameters is not supported, is misspelled, or the value is wrong.
404 - Language direction is not found
This error occurs when the requested language direction is not supported or available. Refer to the supported language list and check your access key configuration on the Tilde MT platform if you've limited it to specific translation languages.
413 - Maximum text size limit reached for the request
This error occurs when the request size reaches the size limit.
To avoid request size limits and potential timeouts, segment large text bodies into smaller chunks (like paragraphs or sentences) and send each in a separate API call.
429 - Too many requests
If you receive this error, retry the request after a short delay. If it persists, progressively increase the delay between retries until the request is successful.
500 - An unexpected error occured
50X are internal errors. You should contact support and provide as much detail as possible about the request, including the data sent and the time of the error, so we can investigate.
504 - Request timed out
To avoid potential timeouts, segment large text bodies into smaller chunks (like paragraphs or sentences) and send each in a separate API call. If the error persists contact support.
Translate files
Tilde MT API supports the following file formats: .docx, .doc, .docm, .xlsx, .pptx, .pdf, .odt, .odp, .ods, .txt, .rtf, .pages, .sxw, .jpg, .jpeg, .png, .bmp, .sdlxliff, .sdlxlf, .ttx, .tmx, .xlf, .xlif, .xliff, .html, .htm, .json, .xhtml, .xht, .tex, .srt. Maximum file size is 25MB.
Methods
| Method | Type | Description |
|---|---|---|
/translate/file | POST | Uploads file and creates translation task. Returns task id, status and other details. |
/translate/file/{task} | GET | Gets details about translation task including translation status. |
/translate/file/{task}/{file} | GET | Downloads the translated file associated with the translation task. |
Step 1: Upload file
To translate a file you'll make a POST multipart/form-data request to the /translate/file endpoint. The request uploads a file and creates a file translation task. It is queued for translation and the call returns the task id. The id is used in further requests to query the translation status and download the translated file.
- cURL
curl -X 'POST' \
'{BASE_URL}/api/translate/file' \
-H 'accept: text/plain' \
-H 'Content-Type: multipart/form-data' \
-H 'X-Api-Key: YOUR_API_KEY' \
-F 'file=@my_example_file.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
-F 'srcLang=en' \
-F 'trgLang=lv' \
-F 'domain=general' \
-F 'engineId=' \
-F 'options.breakSegmentsOnBr=true'
{
"id": "17fcb9d6-2e5e-437e-ab7a-57c94f86ef72", //Task ID
"userId": "YOUR_API_KEY",
"srcLang": "en",
"trgLang": "lv",
"domain": "general",
"engineId": "b7657380-8e1b-498e-89bd-a39bae2b3086",
"fileName": "my_example_file.docx",
"createdAt": "2025-06-09T06:17:57.9042898Z",
"status": "Queuing",
"substatus": "Unspecified",
"segments": 0,
"translatedSegments": 0,
"files": [],
"options": {
"breakSegmentsOnBr": false
},
"pdfPageLimit": 0,
"translationCharacterLimit": 0,
"termCollections": []
}
Request body fields
Request body should contain the following fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
file | Form Field (File) | Yes | The document file to be translated. e.g. @my_example_file.docx |
srcLang | Form Field (String) | Yes | The language code for the source document (e.g., en for English). |
trgLang | Form Field (String) | Yes | The language code for the target translation (e.g., lv for Latvian). |
domain | Form Field (String) | No | Specifies a translation domain (e.g., general, general ai, custom). |
engineId | Form Field (String) | No | The ID of a specific, custom translation engine. Leave empty to use the default engine for the language pair. |
options.breakSegmentsOnBr | Form Field (Boolean) | No | If true, the system will create a new sentence segment at each <br> tag found in the source text. |
Responses
200 - OK
{
"id": "TASK_ID",
"userId": "YOUR_API_KEY",
"srcLang": "string",
"trgLang": "string",
"domain": "string",
"engineId": "string",
"fileName": "string",
"createdAt": "timestamp",
"status": "Queuing",
"substatus": "Unspecified",
"segments": 0,
"translatedSegments": 0,
"files": [],
"options": {
"breakSegmentsOnBr": boolean
},
"pdfPageLimit": 0,
"translationCharacterLimit": 0,
"termCollections": []
}
400 - Missing or incorrect parameters
This error occurs when a required parameter of the request is missing or one of the specified parameters is not supported, is misspelled, or the value is wrong.
404 - Language direction not found
This error occurs when the requested language direction is not supported or available. Refer to the supported language list and check your access key configuration on the Tilde MT platform if you've limited it to specific translation languages.
415 - File type is not supported
This error occurs when the requested file format is not supported. Refer to the supported file format list.
500 - Internal translation error occured
50X are internal errors. You should contact support and provide as much detail as possible about the request, including the data sent and the time of the error, so we can investigate.
Step 2: Check the status and wait for translation complete
To get the translation status you'll make a GET request to the /translate/file/{task} endpoint.
We recommend polling the document status with regular intervals and wait for status Completed. Translation time depends on the size of the file and load of the translation engine. Image and .pdf files take longer to process as they are first converted into a translatable format.
Translation status values can be: Queuing, Extracting, Translating, Saving, Completed, Error.
Translated file id will be included in the response once translation is completed, use it in the next step for download.
curl -X 'GET' \
'{BASE_URL}/api/translate/file/{task_id}' \
-H 'accept: text/plain' \
-H 'X-Api-Key: YOUR_API_KEY'
{
"id": "3c2c1c71-099c-4ff0-91fc-55943c7bdcd2",
"userId": "YOUR_API_KEY",
"srcLang": "en",
"trgLang": "lv",
"domain": "general",
"engineId": "b7657380-8e1b-498e-89bd-a39bae2b3086",
"fileName": "my_example_file.docx",
"createdAt": "2025-06-09T07:50:06.421735",
"status": "Completed",
"substatus": "Unspecified",
"segments": 69,
"translatedSegments": 69,
"files": [
{
"id": "c7ce3ec7-cd78-4bbc-8190-7233d7da279d",
"extension": ".docx",
"category": "Source",
"size": 19569
},
{
"id": "fc2fe80a-7933-4437-94ec-67c0c494745e", //Translated file ID
"extension": ".docx",
"category": "Translated",
"size": 17956
}
],
"options": {
"breakSegmentsOnBr": false
},
"pdfPageLimit": 0,
"translationCharacterLimit": 0,
"termCollections": []
}
Step 3: Download translated file
Once the status of translation process is Completed, the translated file can be downloaded. Make a GET request to /translate/file/{task}/{file} endpoint.
curl -X 'GET' \
'{BASE_URL}/api/translate/file/{TASK_ID}/{TRANSLATED_FILE_ID}' \
-H 'accept: text/plain' \
-H 'X-Api-Key: YOUR_API_KEY'