Machine Translation API

Use Tilde MT API to integrate Tilde Machine Translation systems into your solution and to request translations from MT systems.

Introduction

TildeMT API provides programmatic access to TildeMT machine translation. It let's you integrate machine translation functionality into your application, webpage or CAT tool.

Tilde MT API provides both RESTful calling style and SOAP.

There are six methods in the Tilde MT API, but only GetSystemList and Translate are needed to implement the basic functionality.

Name Description
GetSystemList Lists available translation systems to choose preferred language direction and domain
Translate Translate plaintext or text with tags
TranslateEx Translate plaintext or text with tags. This method returns more information about the translation, such as Quality Estimation score, sentence boundaries, and other statistics comparing to Translate.
TranslateArray Translate array of plaintext or text with tags in a single request
TranslateArrayEx Translate array of plaintext or text with tags in a single request. This method returns more information about the translation, such as Quality Estimation score, sentence boundaries, and other statistics comparing to TranslateArray.
UpdateTranslation Update translation with human translation. This is a way how machine translation can learn to translate better.
GetSystemTermCorpora List term corpora attached to the translation system

Web Service Definition Language (WSDL) file for use in SOAP clients can be found at https://www.letsmt.eu/ws/service.svc?singlewsdl

Authentication

All Tilde MT API requests must contain authentication token that identifies user of Tilde MT.

Contact us to get your client-id authorization_token.

Header example of HTTP request with authorization token

GET https://www.letsmt.eu/ws/service.svc/json/GetSystemList?appID=myappid
client-id: authorization_token
GetSystemList method

Lists available translation systems for authenticated user.

Parameters

Name Type Description
appID string Application identifier of your choice
uiLanguageID string Reserved parameter
options string Reserved parameter

Returned value

Short description of main metadata entries of NMT system

Name Type Description
ID string NMT system ID to use in translate methods
SrcLanguage complex Source language *
TrgLanguage complex Target language *
Domain string Translation domain
Title string Title of the NMT system
Description string Description of the NMT system
Metadata complex More metadata of the system

* Language codes comply with standard IETF RFC 5646

Example

Request

GET https://www.letsmt.eu/ws/Service.svc/json/GetSystemList?appID=myappid HTTP/1.1
client-id: authorization_token

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 916
{
"System":[  
{  
"Description":{  
"Language":null,
"Text":null
},
"Domain":"law",
"ID":"smt-ea364952-816a-4491-9fbc-35b41056730a",
"Metadata":[  
{  
"Key":"meta-corpora-parallel-domain",
"Value":"DGT-TM-2007,DGT-TM-2012,Europarl v6,Europarl v7,DGT-TM-2011,JRC-Acquis (v.3.0),DGT-TM-2013"
},
{  
"Key":"meta-corpora-devel",
"Value":"Acquis Dev set"
},
{  
"Key":"meta-corpora-size-mono",
"Value":"25283603"
},
{  
"Key":"score-bleu",
"Value":"0.6666"
},
{  
"Key":"score-bleu-c",
"Value":"0.6491"
}
]
},
...
]
}

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/GetSystemList"
Content-Length: 451
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSystemList xmlns="http://letsmt.eu/translationAPI">
<appID>myappid</appID>
<uiLanguageId></uiLanguageId>
<options></options>
</GetSystemList>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 462
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSystemListResponse xmlns="http://www.letsmt.eu/translationAPI">
<GetSystemListResult>
<System>
<ID>smt-6ad22e20-2277-4c8b-8125-96add0696475</ID>
<SrcLanguage>
<Code>en</Code>
<Name>English</Name>
</SrcLanguage>
<TrgLanguage>
<Code>lv</Code>
<Name>Latvian</Name>
</TrgLanguage>
<Title>English – Latvian (Legislation)</Title>
<Description />
<Domain>Legislation</Domain>
<Metadata>
<Item key="domain">Legislation</Item>
<Item key="gid">tilde</Item>
<Item key="id">smt-6ad22e20-2277-4c8b-8125-96add0696475</Item>
<Item key="name">English – Latvian (Legislation)</Item>
<Item key="public">true</Item>
<Item key="resource-type">model</Item>
<Item key="score-bleu">0.5020</Item>
<Item key="score-nist">8.2038</Item>
<Item key="size-mono">1887339</Item>
<Item key="size-parallel">1780539</Item>
<Item key="srclang">en</Item>
<Item key="status">running</Item>
<Item key="trglang">lv</Item>
<Item key="uid">bob</Item>
<Item key="translators-running">2</Item>
</Metadata>
</System>
</GetSystemListResult>
</GetSystemListResponse>
</soap:Body>
</soap:Envelope>

Status of NMT systems

NMT system can have one status of a set of statuses. In some statuses NMT system can be used for translation and in some statuses it cannot, because it may not yet be trained or started.

Status code for the system is stored in the metadata of the system in the following key

//System/Metadata/Item[@key='status']

 

Here below is a description of possible status codes

Name Translation allowed Status Code Description
Not Trained   nottrained System is not trained
Queuing Training   queuingtrain System training is about to start
Training canceled   canceled System training is canceled
Training   training System is training
Error   error System training has stopped with error
Not Started   notstarted System is successfully trained and can be started to do translation
Running running System is running and ready to translate
Queuing Translator queuingtransl System is about to be started
Stand-by standby System is in stand-by

End-user of translation application should see that systems in status running, queuingtransl, or standby are available for translation. User can request translation to systems in one of these statuses.

If a system is in status standby or queuingtransl then translation request will wake up the system and exception explaining that system is starting is returned. The system will be ready to translate in a few minutes of time. See more about possible error codes in a description of Translate method.

Translate method

Translates plaintext or text with inline tags using the specified translation system. Optionally term corpus can be specified with the request.

Parameters

Name Type Description
appID string Application identifier of your choice
systemID string Translation system ID
text string Plaintext or text with inline tags
options string Translation options like choice of terminology dictionary.

To use term corpus in translation, set this value in the format termCorpusId=CORPUS_ID.
Term corpora assigned for the system can be listed using GetSystemTermCorpora method where necessary value of CORPUS_ID can be read.

Return value

Translated text.

Possible error codes:

ID Name Description
11 dayLimitReached Daily translation limit has been reached. To raise the daily limit, please contact support: mt@tilde.com.
12 textSizeLimitExceeded Maximum text size limit reached. Please send less text within a request. To raise the text size limit, please contact support: mt@tilde.com.
21 systemIsStarting Your system is starting. You will be able to translate in a few moments.
22 systemNotFound Translation system not found. Please contact support: mt@tilde.com.
23 systemNotStarted Your system is not started. Please start the system to translate or contact support: mt@tilde.com.
0 systemTranslationFailed System level error occured. Please contact support: mt@tilde.com. Error reason: MESSAGE_TEXT.
41 unknownTermCorpusId Unknown term corpus ID provided. Please provide term corpus ID attached to the system or contact support: mt@tilde.com.

Error example:

code: 22
exception: systemNotFound
description: Translation system not found

Example

Request

GET https://www.letsmt.eu/ws/service.svc/json/Translate?appID=myappid&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475&text=saule%20sp%C4%ABd%20spo%C5%BEi&options= HTTP/1.1
client-id: authorization_token

or

POST https://www.letsmt.eu/ws/service.svc/json/Translate HTTP/1.1
client-id: authorization_token
Content-Type: application/json; charset=utf-8
Content-Length: 135
{
"appID": "myappid",
"systemID": "smt-6ad22e20-2277-4c8b-8125-96add0696475",
"text": "saule spīd spoži",
"options": ""
}

POST requests are desired for translating longer text.

Response

HTTP/1.1 200 OK
Content-Length: 23
Content-Type: application/json; charset=utf-8
"the sun shines bright"

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/Translate"
Content-Length: 543
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<Translate xmlns="http://letsmt.eu/translationAPI">
<appID>myappid</appID>
<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
<text>Today is sunny</text>
<options></options>
</Translate>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 401
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<TranslateResponse xmlns="http://letsmt.eu/translationAPI">
<TranslateResult>Šodien ir saulains</TranslateResult>
</TranslateResponse>
</soap:Body>
</soap:Envelope>
TranslateArray method

Translates array of plaintext or text with inline tags using the specified translation system.

Parameters

Name Type Description
appID string Application identifier of your choice
systemID string Translation system ID
textArray string[] Array of plaintext or text with inline tags
options string Translation options like choice of terminology dictionary

Return value

Array of translated text.

The same error codes possible as for Translate method.

Example

Request

GET https://www.letsmt.eu/ws/service.svc/json/TranslateArray?appID=myappid&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475&textArray=[%22saule%20sp%C4%ABd%20spo%C5%BEi%22,%22zirnis%20ir%20%C4%93diens%22]&options= HTTP/1.1
client-id: authorization_token

or

POST https://www.letsmt.eu/ws/service.svc/json/TranslateArray HTTP/1.1
client-id: authorization_token
Content-Type: application/json; charset=utf-8
Content-Length: 157
{
"appID": "myappid",
"systemID": "smt-6ad22e20-2277-4c8b-8125-96add0696475",
"textArray": ["saule spīd spoži", "zirnis ir ēdiens"],
"options": ""
}

POST requests are desired for translating longer text.

Response

HTTP/1.1 200 OK
Content-Length: 23
Content-Type: application/json; charset=utf-8
["the sun shines bright","the food is pea"]

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/TranslateArray"
Content-Length: 603
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soap:Body>
<TranslateArray xmlns="http://letsmt.eu/translationAPI">
<appID>myappid</appID>
<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
<textArray>
<a:string>Today is sunny</a:string>
<a:string>Tomorrow is going to be cloudy</a:string>
</textArray>
<options></options>
</TranslateArray>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 501
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soap:Body>
<TranslateArrayResponse xmlns="http://letsmt.eu/translationAPI">
<TranslateArrayResult>
<a:string>Šodien ir saulains</a:string>
<a:string>Rīt būs mākoņains</a:string>
</TranslateArrayResult>
</TranslateArrayResponse>
</soap:Body>
</soap:Envelope>
TranslateArrayEx method

Translate array of plaintext or text with tags in a single request. This method returns more information about the translation, such as Quality Estimation score, sentence boundaries, and other statistics comparing to TranslateArray.

Parameters

Name Type Description
appID string Application identifier of your choice
systemID string Translation system ID
textArray string[] Array of plaintext or text with inline tags
options string Translation options like choice of terminology dictionary

Return value

Array of translated text.

Each element in the array consists of the following attributes:

Name Type Description
countSentences int Total count of sentences in the text item
countTokens int Total count of tokens in the text item
originalSentenceRanges int[][] Array of pairs - character position of sentence start and count of characters in the original text
qualityEstimate decimal Quality Estimation (QE) score of the item text in range 0 to 1. Bigger value means better translation quality. Add qe value to options parameter in order to enable QE scoring. More values in the options parameter can be split by comma ,.
translation string Translation of the original text
translationSentenceRanges int[][] Array of pairs - character position of translation sentence start and count of characters in the translated text

The same error codes possible as for Translate method.

Example

Request

GET https://www.letsmt.eu/ws/service.svc/json/TranslateArrayEx?appID=myappid&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475&textArray=[%22Saule%20sp%C4%ABd%20spo%C5%BEi. Zirnis%20ir%20%C4%93diens%22]&options= HTTP/1.1
client-id: authorization_token

or

POST https://www.letsmt.eu/ws/service.svc/json/TranslateArrayEx HTTP/1.1
client-id: authorization_token
Content-Type: application/json; charset=utf-8
Content-Length: 157
{
"appID": "myappid",
"systemID": "smt-6ad22e20-2277-4c8b-8125-96add0696475",
"textArray": ["Today is sunny. Tomorrow is going to be cloudy"],
"options": ""
}

POST requests are desired for translating longer text.

Response

HTTP/1.1 200 OK
Content-Length: 701
Content-Type: application/json; charset=utf-8
[  
{  
"countSentences":2,
"countTokens":10,
"originalSentenceRanges":[  
[  
0,
15
],
[  
15,
31
]
],
"qualityEstimate":0.83,
"translation":"Šodien ir saulains. Rīt būs mākoņains",
"translationSentenceRanges":[  
[  
0,
19
],
[  
19,
18
]
]
}
]

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/TranslateArrayEx"
Content-Length: 603
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soap:Body>
<TranslateArrayEx xmlns="http://letsmt.eu/translationAPI">
<appID>myappid</appID>
<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
<textArray>
<a:string>Today is sunny. Tomorrow is going to be cloudy</a:string>
</textArray>
<options></options>
</TranslateArrayEx>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 1307
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<TranslateArrayExResponse xmlns="http://letsmt.eu/translationAPI">
<TranslateArrayExResult xmlns:a="http://schemas.datacontract.org/2004/07/Tilde.TextProcessor" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:TranslateResult>
<a:countSentences>2</a:countSentences>
<a:countTokens>10</a:countTokens>
<a:originalSentenceRanges xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:ArrayOfint>
<b:int>0</b:int>
<b:int>15</b:int>
</b:ArrayOfint>
<b:ArrayOfint>
<b:int>15</b:int>
<b:int>31</b:int>
</b:ArrayOfint>
</a:originalSentenceRanges>
<a:qualityEstimate>0.83</a:qualityEstimate>
<a:translation>Šodien ir saulains. Rīt būs mākoņains</a:translation>
<a:translationSentenceRanges xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:ArrayOfint>
<b:int>0</b:int>
<b:int>19</b:int>
</b:ArrayOfint>
<b:ArrayOfint>
<b:int>19</b:int>
<b:int>18</b:int>
</b:ArrayOfint>
</a:translationSentenceRanges>
</a:TranslateResult>
</TranslateArrayExResult>
</TranslateArrayExResponse>
</s:Body>
</s:Envelope>
UpdateTranslation method

Suggest a better translation of a sentence

Parameters

Name Type Description
appID string Application identifier of your choice
systemID string Translation system ID
text string Original plaintext or text with inline tags
translationtext string Human translation of the original text
options string Reserved parameter

Return value

The method does not have a return value

Example

Request

GET https://www.letsmt.eu/ws/service.svc/json/UpdateTranslation?appID=myappid&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475&text=%C5%A0odien%20sp%C4%ABd%20saule&translation=The%20sun%20is%20shining%20today&options= HTTP/1.1
client-id: authorization_token

or

POST https://www.letsmt.eu/ws/service.svc/json/UpdateTranslation HTTP/1.1
client-id: authorization_token
Content-Type: application/json; charset=utf-8
Content-Length: 177
{
"appID": "myappid",
"systemID": "smt-6ad22e20-2277-4c8b-8125-96add0696475",
"text": "Šodien spīd saule",
"translation": "The sun is shining today",
"options": ""
}

POST requests are desired for translating longer text.

Response

HTTP/1.1 200 OK
Content-Length: 0

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/UpdateTranslation"
Content-Length: 519
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<UpdateTranslation xmlns="http://hugo.lv/translationAPI">
<appID>myappid</appID>
<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
<text>Šodien spīd saule</text>
<translation>Sun is shining today</translation>
<options></options>
</UpdateTranslation>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 327
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<UpdateTranslationResponse xmlns="http://hugo.lv/translationAPI" />
</soap:Body>
</soap:Envelope>
GetSystemTermCorpora method

List term corpora of the translation system

Parameters

Name Type Description
systemID string Translation system ID

Return value

List of term corpora. Attributes of term corpus list item:

Name Type Description
CorpusId string Term corpus ID. This value must be set in options of a translation request in a format termCorpusId=CORPUS_ID.
Title string Title or display name of term corpus
Type string Either public or private clarifying whether a term corpus is available for everyone or active user
Status string  

There are couple of status values possible for a term corpus. Term corpus in a status Ready can be used in the translation.

Possible status values:

Status Description
Ready Term corpus is ready for use in translation
ImportedInDatabase Term corpus is imported but not yet ready for translation
ForDeletion Term corpus is going to be deleted. Not ready for translation.
Attached Term corpus is attached to the system but not yet ready for translation

Example

Request

GET https://www.letsmt.eu/ws/service.svc/json/GetSystemTermCorpora?systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475 HTTP/1.1
client-id: authorization_token

Response

HTTP/1.1 200 OK
Content-Length: 319
Content-Type: application/json; charset=utf-8
[  
{  
"CorpusId":"c-67e1260a-94f2-48d6-b9cd-cbceee89310d",
"Title":"Project NR. 2456",
"Type":"private",
"Status":"Ready"
},
{  
"CorpusId":"c-2cb5af50-60b6-4508-9d41-95adee23e98f",
"Title":"Microsoft IT",
"Type":"private",
"Status":"Ready"
}
]

Request

POST https://www.letsmt.eu/ws/service.svc/soap HTTP/1.1
client-id: authorization_token
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://letsmt.eu/translationAPI/ITranslationServiceContract/GetSystemTermCorpora"
Content-Length: 443
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSystemTermCorpora xmlns="http://letsmt.eu/translationAPI">
<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
</GetSystemTermCorpora>
</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 697
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSystemTermCorporaResponse xmlns="http://letsmt.eu/translationAPI">
<GetSystemTermCorporaResult xmlns:a="http://www.tilde.com/LetsMT/SystemManager" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:TermCorpus>
<a:CorpusId>c-67e1260a-94f2-48d6-b9cd-cbceee89310d</a:CorpusId>
<a:Title>Project NR. 2456</a:Title>
<a:Type>private</a:Type>
<a:Status>Ready</a:Status>
</a:TermCorpus>
<a:TermCorpus>
<a:CorpusId>c-2cb5af50-60b6-4508-9d41-95adee23e98f</a:CorpusId>
<a:Title>Microsoft IT</a:Title>
<a:Type>private</a:Type>
<a:Status>Ready</a:Status>
</a:TermCorpus>
</GetSystemTermCorporaResult>
</GetSystemTermCorporaResponse>
</soap:Body>
</soap:Envelope>
GET https://www.letsmt.eu/ws/service.svc/json/GetSystemList?appID=myappid
client-id: authorization_token