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
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.
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. |
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>
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>
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>
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>
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