Tilde MT API deliver machine translation to your solution.

Introduction

This paper describe 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.

Tilde MT API provide SOAP and simple HTTP request (using JSON serialization) protocols.

There are 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
Translate Translate plaintext or text with tags
TranslateEx Translate plaintext or text with tags. This method return more information about the translation, like, Quality Estimation score, sentence boundaries, and other statistics.
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 return more information about the translation, like, Quality Estimation score, sentence boundaries, and other statistics.
UpdateTranslation Update translation with human translation or post-edit. This is a way how machine translation can be learn to translate better.
GetSystemTermCorpora List term corpora attached to the translation system

Document translation methods for various document format translation.

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

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 be authenticated using authentication token (client-id).

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

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 of a set of statuses. In some statuses SMT system can be used for translation and in some statuses it cannot, because it may not jet 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 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>
TranslateArray method

Translates 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 array of plaintext or text with tags in a single request. This method return more information about the translation, like, 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. 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

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

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 document and start translation task using selected translation system. Optionally term corpus can be specified with the request.

Currently we support DOC, DOCX, XLSX, PPTX, ODT, ODP, ODS, FODT, FODP, FODS, HTML, HTM, XHTML, XHT, TXT, TMX, XLF, XLIF, XLIFF, SDLXLIFF, TTX, RTF, PAGES file formats. 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 show 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

Get state 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 consist 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: TODO

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 list of all document translation tasks

Parameters

Name Type Description
appID string Identifier of your application

Return value

Array of document translation task state objects. Se detailed description of the objec 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>