The Tilde MT API delivers machine translation to your solution.

Introduction

This paper describes programmatic interaction with Tilde MT from other applications. The paper is intended for developers who want to integrate machine translation functionality to their application, webpage, or CAT (Computer-Assisted Translation) tool.

The Tilde MT API provides SOAP and simple HTTP request (using JSON serialization) protocols. The Tilde MT API also consists of a system selection web component, which is a Tilde MT configuration dialog where the user of your CAT tool can acquire an authentication token, select the available language directions and MT systems with all the necessary adjustments of terminology, Quality Estimation, and more.

There are a few simple methods in the Tilde MT API, but you can only start with the first two to implement the basic text translation functionality.

Name Description
GetSystemList

List available translation systems to choose preferred language direction and domain.

In case you are implementing Tilde MT in a CAT tool, please check the system selection web component first. The web component already implements acquisition of authentication token, calls of GetSystemList and GetSystemTermCorpora methods, and other configuration adjustments. You can save a lot of development time implementing complex configuration dialog of Tilde MT by using the system selection web component.

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.
TranslateArray Translate an array of plaintext or text with tags in a single request
TranslateArrayEx Translate an 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.
UpdateTranslation Update translations with human translations or post-edits. In this way, machine translation can learn to translate even better and improve over time.
GetSystemTermCorpora List term corpora attached to the translation system. You don't need to implement call of this method once you integrate the system selection web component.

Document translation methods for translation of various document formats.

Name Description
StartDocumentTranslation Upload document and start translating
GetDocumentTranslationState See the status of a document translation task
DownloadDocumentTranslation Download translated document
RemoveDocumentTranslation Delete document translation task and all related documents
GetDocumentTranslationList Get a list of all document translation tasks

Web Service Definition Language (WSDL) file for SOAP users is here https://www.letsmt.eu/ws/service.svc?singlewsdl

Authentication

All Tilde MT API requests must be authenticated using authentication token (client-id).

Contact us to get your client-id authorization_token or integrate system selection web component in your application, so that a user of our application can acquire authentication token by themselves.

Header example of HTTP request with authorization token

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

Each method of the API has appID parameter. Please set your application's or CAT tool's name as the value of the parameter.

GetSystemList method

List available translation systems for authenticated user.

Parameters

Name Type Description
appID string Identifier of your application
uiLanguageID string Reserved parameter
options string Reserved parameter

Returned value

Short description of main metadata entries of SMT system

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

* Language codes comply with standard IETF RFC 5646

Example

JSON
SOAP

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 SMT systems

SMT system can have one status or a set of statuses. In some statuses a SMT system can be used for translation; in other 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']

 

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 an exception is returned explaining that the system is starting. The system will be ready to translate in a few minutes. See more about possible error codes in a description of Translate method.

Translate method

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

Parameters

Name Type Description
appID string Identifier of your application
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

JSON
SOAP

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>
TranslateEx method

Translates plaintext or text with inline tags using the specified translation system. Optionally, a term corpus can be specified with the request. This method returns more information about the translation, such as Quality Estimation score, sentence boundaries, and other statistics comparing to Translate.

PARAMETERS

Name Type Description
appID string Identifier of your application
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 with additional information:

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

Error example:

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

EXAMPLE

JSON
SOAP

Request

GET https://www.letsmt.eu/ws/service.svc/json/TranslateEx?appID=myappid&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475&text=Today%20is%20sunny.%20Tomorrow%20is%20going%20to%20be%20cloudy&options= HTTP/1.1
client-id: authorization_token

or

POST https://www.letsmt.eu/ws/service.svc/json/TranslateEx 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": "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: 619
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/TranslateEx"
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>
		<TranslateEx xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
			<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
			<text>Today is sunny. Tomorrow is going to be cloudy</text>
			<options></options>
		</TranslateEx>
	</soap:Body>
</soap:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 1401
<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>
		<TranslateExResponse xmlns="http://letsmt.eu/translationAPI">
			<TranslateExResult xmlns:a="http://schemas.datacontract.org/2004/07/Tilde.TextProcessor" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
				<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>
			</TranslateExResult>
		</TranslateExResponse>
	</soap:Body>
</soap:Envelope>
TranslateArray method

Translates an array of plaintext or text with inline tags using selected translation system.

Parameters

Name Type Description
appID string Identifier of your application
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

JSON
SOAP

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 an 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 Identifier of your application
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 consist 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. A 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 a 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

JSON
SOAP

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 Identifier of your application
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

JSON
SOAP

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://letsmt.eu/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://letsmt.eu/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 an active user
Status string  

There are couple of possible status values for a term corpus. Term corpus in 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

JSON
SOAP

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>
StartDocumentTranslation method

Upload a document and start the translation task using a selected translation system. Optionally, a term corpus can be specified with the request.

Currently we support the following file formats: DOC, DOCX, XLSX, PPTX, ODT, ODP, ODS, FODT, FODP, FODS, HTML, HTM, XHTML, XHT, TXT, TMX, XLF, XLIF, XLIFF, SDLXLIFF, TTX, RTF, PAGES. UTF-8 or UTF-16 coding required for plaintext document formats.

Parameters

Name Type Description
appID string Identifier of your application
fileName string File name of the document
content byte[] Binary content of the document
systemID string Translation system ID
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

Identifier of document translation task.

Possible error codes:

ID Name Description
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: 41 exception: unknownTermCorpusId description: Unknown term corpus ID provided. Please provide term corpus ID attached to the system or contact support: mt@tilde.com.

Example

The example shows how to translate a sample.txt document with the following content:

"Sometimes our translation needs are limited to just a few phrases or sentences. 
But more often than not, users need to translate entire documents.
Tilde’s MT technology provides for full document translation. 
Best of all, users can upload documents in several file formats, including DOCX, TXT, TMX, and XLIFF."
JSON
SOAP

Request

POST https://www.letsmt.eu/ws/service.svc/json/StartDocumentTranslation HTTP/1.1
client-id: authorization_token
Content-Type: application/json; charset=utf-8
Content-Length: 1317
{
	"appID": "myappid",
	"fileName": "sample.txt",
	"content": [239,187,191,83,111,109,101,116,105,109,101,115,32,111,117,114,32,116,114,97,110,115,108,97,116,105,111,110,32,110,101,101,100,115,32,97,114,101,32,108,105,109,105,116,101,100,32,116,111,32,106,117,115,116,32,97,32,102,101,119,32,112,104,114,97,115,101,115,32,111,114,32,115,101,110,116,101,110,99,101,115,46,32,13,10,66,117,116,32,109,111,114,101,32,111,102,116,101,110,32,116,104,97,110,32,110,111,116,44,32,117,115,101,114,115,32,110,101,101,100,32,116,111,32,116,114,97,110,115,108,97,116,101,32,101,110,116,105,114,101,32,100,111,99,117,109,101,110,116,115,46,13,10,84,105,108,100,101,226,128,153,115,32,77,84,32,116,101,99,104,110,111,108,111,103,121,32,112,114,111,118,105,100,101,115,32,102,111,114,32,102,117,108,108,32,100,111,99,117,109,101,110,116,32,116,114,97,110,115,108,97,116,105,111,110,46,32,13,10,66,101,115,116,32,111,102,32,97,108,108,44,32,117,115,101,114,115,32,99,97,110,32,117,112,108,111,97,100,32,100,111,99,117,109,101,110,116,115,32,105,110,32,115,101,118,101,114,97,108,32,102,105,108,101,32,102,111,114,109,97,116,115,44,32,105,110,99,108,117,100,105,110,103,32,68,79,67,88,44,32,84,88,84,44,32,84,77,88,44,32,97,110,100,32,88,76,73,70,70,46],
	"systemID": "smt-6ad22e20-2277-4c8b-8125-96add0696475",
	"options": ""
}

Response

HTTP/1.1 200 OK
Content-Length: 40
Content-Type: application/json; charset=utf-8
"d-5e9addda-af51-42df-ab4a-ef4d84dcd24f"

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/StartDocumentTranslation"
Content-Length: 800
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<StartDocumentTranslation xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
			<fileName>sample.txt</fileName>
			<content>U29tZXRpbWVzIG91ciB0cmFuc2xhdGlvbiBuZWVkcyBhcmUgbGltaXRlZCB0byBqdXN0IGEgZmV3IHBocmFzZXMgb3Igc2VudGVuY2VzLiAKQnV0IG1vcmUgb2Z0ZW4gdGhhbiBub3QsIHVzZXJzIG5lZWQgdG8gdHJhbnNsYXRlIGVudGlyZSBkb2N1bWVudHMuClRpbGRl4oCZcyBNVCB0ZWNobm9sb2d5IHByb3ZpZGVzIGZvciBmdWxsIGRvY3VtZW50IHRyYW5zbGF0aW9uLiAKQmVzdCBvZiBhbGwsIHVzZXJzIGNhbiB1cGxvYWQgZG9jdW1lbnRzIGluIHNldmVyYWwgZmlsZSBmb3JtYXRzLCBpbmNsdWRpbmcgRE9DWCwgVFhULCBUTVgsIGFuZCBYTElGRi4=</content>
			<systemID>smt-6ad22e20-2277-4c8b-8125-96add0696475</systemID>
			<options></options>
		</StartDocumentTranslation>
	</s:Body>
</s:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 306
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<StartDocumentTranslationResponse xmlns="http://letsmt.eu/translationAPI">
			<StartDocumentTranslationResult>d-cced92e2-6a0e-4aa2-b911-f9bb452951b7</StartDocumentTranslationResult>
		</StartDocumentTranslationResponse>
	</s:Body>
</s:Envelope>
GetDocumentTranslationState method

See the status of a document translation task

Parameters

Name Type Description
appID string Identifier of your application
id string Identifier of document translation task

Return value

Status object of the document translation task.

Status consists of the following relevant attributes about a document translation task:

Name Type Description
Id string Identifier of document translation task
Segments int Total count of text segments
TranslatedSegments int Count of translated text segments
Size int Size of the file in bytes
Filename string Filename of the document
Status string

Status of the document translation task

Possible status codes:

  • queuing - queuing for resources to start docuemnt translation task
  • waiting - waiting for translation system to start
  • translating - translating document
  • completed - document translation is completed and translated document is ready to download
  • error - error has occurred executing document translation task
System string Translation system ID
ErrroCode string Error code
ErrorMessage string Error message

Example

JSON
SOAP

Request

GET https://www.letsmt.eu/ws/service.svc/json/GetDocumentTranslationState?appID=myappid&id=d-6e65df52-ad80-4a2e-ac19-05b85d24c733 HTTP/1.1
client-id: authorization_token

Response

HTTP/1.1 200 OK
Content-Length: 704
Content-Type: application/json; charset=utf-8
{ 
	"ErrorCode":null,
	"ErrorMessage":null,
	"Filename":"sample.txt",
	"Id":"d-6e65df52-ad80-4a2e-ac19-05b85d24c733",
	"Segments":4,
	"Size":320,
	"Status":"queuing",
	"System":"smt-6ad22e20-2277-4c8b-8125-96add0696475", 
	"TranslatedSegments":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/GetDocumentTranslationState"
Content-Length: 288
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<GetDocumentTranslationState xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
			<id>d-6e65df52-ad80-4a2e-ac19-05b85d24c733</id>
		</GetDocumentTranslationState>
	</s:Body>
</s:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 727
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<GetDocumentTranslationStateResponse xmlns="http://letsmt.eu/translationAPI">
			<GetDocumentTranslationStateResult xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
				<a:ErrorCode i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
				<a:ErrorMessage i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
				<a:Filename>sample.txt</a:Filename>
				<a:id>d-6e65df52-ad80-4a2e-ac19-05b85d24c733</a:id>
				<a:Segments>4</a:Segments>
				<a:Size>314</a:Size>
				<a:Status>queuing</a:Status>
				<a:System>smt-6ad22e20-2277-4c8b-8125-96add0696475</a:System>
				<a:TranslatedSegments>0</a:TranslatedSegments>
			</GetDocumentTranslationStateResult>
		</GetDocumentTranslationStateResponse>
	</s:Body>
</s:Envelope>
DownloadDocumentTranslation method

Download translated document

Parameters

Name Type Description
appID string Identifier of your application
id string Identifier of document translation task

Return value

Document translation as byte[]

Example

JSON
SOAP

Request

GET https://www.letsmt.eu/ws/service.svc/json/DownloadDocumentTranslation?appID=myappid&id=d-593daee7-69ec-4437-8835-154b2a02cfce HTTP/1.1
client-id: authorization_token

Response

HTTP/1.1 200 OK
Content-Length: 31
Content-Type: application/json; charset=utf-8
[68,97,197,190,114,101,105,122,32,109,197,171,115,117,32,116,117,108,107,111,197,161,97,110,97,115,32,118,97,106,97,100,122,196,171,98,97,115,32,97,112,114,111,98,101,197,190,111,106,97,115,32,97,114,32,112,196,129,114,105,115,32,102,114,196,129,122,196,147,109,32,118,97,105,32,116,101,105,107,117,109,105,101,109,46,10,13,10,84,97,196,141,117,32,118,105,115,98,105,101,197,190,196,129,107,44,32,108,105,101,116,111,116,196,129,106,105,101,109,32,110,101,112,105,101,99,105,101,197,161,97,109,115,32,116,117,108,107,111,116,32,118,105,115,117,32,100,111,107,117,109,101,110,116,117,46,10,13,10,84,105,108,100,101,32,226,128,153,32,115,32,77,84,32,116,101,104,110,111,108,111,196,163,105,106,97,32,112,97,114,101,100,122,32,112,105,108,110,196,171,103,117,32,100,111,107,117,109,101,110,116,97,32,116,117,108,107,111,106,117,109,117,46,10,13,10,86,105,115,108,97,98,196,129,107,97,105,115,44,32,108,105,101,116,111,116,196,129,106,105,32,118,97,114,32,97,117,103,197,161,117,112,105,101,108,196,129,100,196,147,116,32,100,111,107,117,109,101,110,116,117,115,32,100,97,197,190,196,129,100,111,115,32,102,97,105,108,117,32,102,111,114,109,196,129,116,111,115,44,32,105,101,115,107,97,105,116,111,116,32,68,79,67,88,44,32,84,88,84,44,32,84,77,88,44,32,117,110,32,88,76,73,70,70,46,13,10]

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/DownloadDocumentTranslation"
Content-Length: 288
<s:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<DownloadDocumentTranslation xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
			<id>d-593daee7-69ec-4437-8835-154b2a02cfce</id>
		</DownloadDocumentTranslation>
	</s:Body>
</s:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 744
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<DownloadDocumentTranslationResponse xmlns="http://letsmt.eu/translationAPI">
			<DownloadDocumentTranslationResult>c2F1c2FnZQo=</DownloadDocumentTranslationResult>
		</DownloadDocumentTranslationResponse>
	</s:Body>
</s:Envelope>

Translation of sample.txt in text format:

"Dažreiz mūsu tulkošanas vajadzības aprobežojas ar pāris frāzēm vai teikumiem.
Taču visbiežāk, lietotājiem nepieciešams tulkot visu dokumentu.
Tilde ’ s MT tehnoloģija paredz pilnīgu dokumenta tulkojumu.
Vislabākais, lietotāji var augšupielādēt dokumentus dažādos failu formātos, ieskaitot DOCX, TXT, TMX, un XLIFF."
RemoveDocumentTranslation method

Delete document translation task and all related documents

Parameters

Name Type Description
appID string Identifier of your application
id string Identifier of document translation task

Return value

The method does not have a return value

Example

JSON
SOAP

Request

GET https://www.letsmt.eu/ws/service.svc/json/RemoveDocumentTranslation?appID=myappid&id=d-593daee7-69ec-4437-8835-154b2a02cfce HTTP/1.1
client-id: authorization_token

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/RemoveDocumentTranslation"
Content-Length: 284
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<RemoveDocumentTranslation xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
			<id>d-593daee7-69ec-4437-8835-154b2a02cfce</id>
		</RemoveDocumentTranslation>
	</s:Body>
</s:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 327
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<RemoveDocumentTranslationResponse xmlns="http://letsmt.eu/translationAPI" />
	</s:Body>
</s:Envelope>
GetDocumentTranslationList method

Get a list of all document translation tasks

Parameters

Name Type Description
appID string Identifier of your application

Return value

Array of document translation task status objects. See a detailed description of the object in GetDocumentTranslationState method.

Example

JSON
SOAP

Request

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

Response

HTTP/1.1 200 OK
Content-Length: 701
Content-Type: application/json; charset=utf-8
[
	{
		"ErrorCode":null,
		"ErrorMessage":null,
		"Filename":"aaa.txt",
		"Id":"d-6e65df52-ad80-4a2e-ac19-05b85d24c733",
		"Segments":0,
		"Size":4,
		"Status":"queuing",
		"System":"smt-6ad22e20-2277-4c8b-8125-96add0696475",
		"TranslatedSegments":0
	},
	{
		"ErrorCode":null,
		"ErrorMessage":null,
		"Filename":"bbb.txt",
		"Id":"d-7de5df52-ad80-4a2e-ac19-05b85d24c730",
		"Segments":10,
		"Size":5,
		"Status":"completed",
		"System":"smt-6ad22e20-2277-4c8b-8125-96add0696475",
		"TranslatedSegments":10
	},
]

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/GetDocumentTranslationList"
Content-Length: 234
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<GetDocumentTranslationList xmlns="http://letsmt.eu/translationAPI">
			<appID>myappid</appID>
		</GetDocumentTranslationList>
	</s:Body>
</s:Envelope>

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 1377
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<GetDocumentTranslationListResponse xmlns="http://letsmt.eu/translationAPI">
			<GetDocumentTranslationListResult xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
				<a:Document>
					<a:ErrorCode i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
					<a:ErrorMessage i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
					<a:Filename>sample.txt</a:Filename>
					<a:id>d-6e65df52-ad80-4a2e-ac19-05b85d24c733</a:id>
					<a:Segments>4</a:Segments>
					<a:Size>314</a:Size>
					<a:Status>completed</a:Status>
					<a:System>smt-6ad22e20-2277-4c8b-8125-96add0696475</a:System>
					<a:TranslatedSegments>4</a:TranslatedSegments>
				</a:Document>
				<a:Document>
					<a:ErrorCode i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
					<a:ErrorMessage i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/LetsMT.Translation"/>
					<a:Filename>notes.txt</a:Filename>
					<a:id>d-7de5df52-ad80-4a2e-ac19-05b85d24c730</a:id>
					<a:Segments>10</a:Segments>
					<a:Size>5</a:Size>
					<a:Status>queuing</a:Status>
					<a:System>smt-6ad22e20-2277-4c8b-8125-96add0696475</a:System>
					<a:TranslatedSegments>0</a:TranslatedSegments>
				</a:Document>
			</GetDocumentTranslationListResult>
		</GetDocumentTranslationListResponse>
	</s:Body>
</s:Envelope>

Tilde MT system selection web component

The Tilde MT system selection web component is a standalone tool for managing settings in a CAT tool that integrates with the Tilde MT API. It allows the user to authenticate in the Tilde MT platform and retrieves a list of machine translation systems available for the user. A different system can be selected for each of the available source and target language pairs. The web component automatically manages the retrieval of the system list and configuration of the individual translation systems, as well as provides the appropriate request parameters to be used when making a text translation request to the Tilde MT API.

The user interface of the web component has two views. First is the authentication view, where a user can enter their Client ID or follow the "Get my Client ID" link to acquire one:

After succesful authentication, the MT system configuration view is shown:

It is implemented as a Web Component. Only vanilla JS is used. When using the webcomponents.js polyfill browser support should go back as far as IE10.

Prerequisites

You might want to include the webcomponents.js polyfill to support older browsers. There are no other dependencies.

Usage

To integrate the Tilde MT system selection web component in a CAT tool or in a similar application, a user must implement several steps:

  • inserting the tildemt-selector custom element in you page's HTML;
  • managing the component's lifecycle by attaching event handlers in JavaScript or by manually triggering state transitions;
  • using the web component's configuration state to make translation requests to the Tilde MT API;
  • persisting and restoring the state to allow subsequent editing of the web component's configuration;
  • optionally customizing the web component's UI.

Including the web component

It is as simple as this:

<html>
<head>
    <link rel="import" href="https://www.letsmt.eu/ws/tildemt-selector.html">
</head>
<body>
    <tildemt-selector id="tildemt"></tildemt-selector>
</body>
</html>

Note: Make sure you always link the web component from www.letsmt.eu. This will let you always use the latest version with all new updates and fixes without having to update files in your integration. We will keep all future versions of the web component backward-compatible with the current one, and no one will ever bother you with a request to implement the very latest feature in the Tilde MT configuration dialog.

Managing the component's lifecycle

During interaction with the component, the user can save the component's state, cancel the changes, or log out from the component effectively dropping any previously saved configuration. These interactions can be managed in two ways:

  • by attaching event handlers to listen for state changes that are triggered by interacting with the built-in save and cancel buttons;
  • or by manually calling saveAndGetState and cancel methods if, for example, the save and cancel buttons are hidden (see customizing the web component's looks).

The logout event cannot be manually triggered. When the component's state is saved the saved configuration is passed via the respective event details or the method return value.

Attaching event handlers

There are three events exposed by the component:

Event Description
save The save event is used to notify that the save button has been pressed indicating that the user has finished selecting systems.
document.getElementById("tildemt").addEventListener("save", function(details){
    // event details contain the selector component's state
    tildemtConfig = details.detail;
    // we'll look at this method in greater detail later
    populateSystemList(tildemtConfig);
});
cancel The event is used to notify that the cancel button has been pressed, indicating that the user has aborted the system selection process and wishes to undo changes.
document.getElementById("tildemt").addEventListener("cancel", function(){
    // use the component's previous state tildemtConfig
});
logout The event notifies that the logout button has been pressed indicating that the web component's state should be dropped so that the user can authenticate with a different Client ID.
document.getElementById("tildemt").addEventListener("logout", function(){
    // drop the saved state
    tildemtConfig = undefined;
});

Manually triggering state changes

The status change can be triggered by either of two method calls. Calling saveAndGetState will manually trigger the component's state save and will return the state similar to the save event.

// this is probably attached to some save buttons event handler or similar
tildemtConfig = document.getElementById("tildemt").saveAndGetState();

Calling the cancel method will trigger the component's cancel event.

// this is probably attached to some cancel buttons event handler or similar
document.getElementById("tildemt").cancel();
// use the component's previous state tildemtConfig

Using the configuration

The status object received via the TildeMT web component's save event has this general structure:

{
    "engineName": "My English-German and English-Latvian engine",
    "client-id": "u-0353d8-ufub-9tga-a59a-io8a3618kb39s",
    "systems": {
        "en-de": {
            "params": {
                "systemID": "smt-83q34k17-2ob6-622l-10hk-1lb669s6ggh0",
                "options": ""}},
        "en-lv": {
            "params": {
                "systemID": "smt-f4b008c1-3152-444b-91f7-2472e0b69b63",
                "options": "qe"}}}
}

Attributes of the status structure:

Attribute Description
engineName

The user can input a name for the newly created system configuration to later identify it. This is useful if the same MT plugin can be used to configure multiple different translation engines. A single user, for example, could be using the Tilde MT platform for two different projects each requiring different translation systems for the same language direction or different authentication tokens.

This field is not needed when making calls to the TildeMT API. If the above described functionality is not needed then the engineName field can be safely ignored. See also Customizing the web component's looks.

client-id Used to authenticate calls to the Tilde MT API. Each call to the API must have a client-id field set in the HTTP request header.
systems

An object with keys corresponding to the different language combinations supported. In the above example the user has selected two translation systems -- for English to German and English to Latvian translations. This is indicated by two ISO 639-1 language codes separated by a dash.

Each of the configured systems contains a params object containing multiple key-value pairs. These (systemID and options) should be set as the query parameters for the API requests for the respective language pair.

An example of a translation request when translating from English to Latvian looks like this:

GET https://www.letsmt.eu/ws/service.svc/json/TranslateEx?appID=myappid
&systemID=smt-6ad22e20-2277-4c8b-8125-96add0696475
&text=Hello%20world&options=qe HTTP/1.1
client-id: authorization_token

maintaining the web component's status

It is recommended to maintain the whole web component's status object as a JSON string.

Saving

This should be as simple as:

// tildemtConfig is acquired via the web components `save` event's details
var stateString = JSON.stringify(tildemtConfig);
saveStateJsonInDb(stateString);

Restoring

After the web component has initially been configuredm the user might want to edit the configuration to, for example, change the selected MT system for one or more languages, add a system for a new language pair, or remove a system altogether. To facilitate this the web component provides a setState method that sets its status to a previous configuration.

// the previous configuration could be stored and retrieved as JSON from the backend
var stateString = getStateJsonFromDb();
tildemtConfig = stateString ? JSON.parse(stateString) : undefined;
document.getElementById("tildemt").setState(tildemtConfig);
// show the web component to the user; the web component will now reload the previously
// selected system list

Customizing the web component's appearance (optional)

One can change certain features of the web component's UI to better align with the parent application's UI. This is achieved by adding attributes to the component's HTML tag.

<tildemt-selector id="tildemt" hiddenname hiddensave reversebuttons></tildemt-selector>

Description of attributes:

Attribute Description
hiddenname Set the attribute to hide the Engine name input field.
hiddensave Hides the component's save and cancel buttons. This is useful if the parent application already has dedicated UI elements for saving and resetting MT plugins' state.
reversebuttons Changes the order of save/continue and cancel buttons.