Page tree

CEF DIGITAL home page

eTranslation Documentation

How to request translations using the eTranslation webservice

Introduction




This is the main document describing machine-to-machine integration of the CEF Automated Translation machine translation service ("eTranslation") through a Web Service call. Additional information including strategic guidelines, the eDelivery submission channel and sample scenarios for different programming languages can be accessed from the wiki structure pane to the left.

The eTranslation web service is asynchronous. This means that the client sends a translation request and is notified later when the text snippet or document is translated. In this way calling the web service does not block the client. However, the client needs to expose a callback URL which will receive a notification that the translation job in question has been completed. eTranslation sends the completed translation to the destination URL specified by the Client.

The following steps illustrate this interaction:

  1. The client sends a translation request to the eTranslation web service ;
  2. eTranslation web service replies synchronously with the eTranslation request ID (positive number) or an error code (negative number) ;
  3. eTranslation web service translates the text or document for all requested target languages ;
  4. Each translated text or document is sent back to the target location and the client can be notified separately for each target language via the callback URL.

The above approach decouples the client from the eTranslation server. It's the responsibility of the Client to submit the initial request, and react to the callback notification from the eTranslation server. eTranslation accepts and sends back an external reference that allows the client to associate the callbacks with the translation requests that the client sent earlier. This way the client knows to which translation request a callback refers to. A better approach we recommend is for the client to use the request ID generated by eTranslation and sent with the translated text or document. The Client should keep track of all pending translation requests by means of an internal list of external references ("external-reference") - or eTranslation request ID ("request-id") and validate all callbacks to the callback URL which corresponds to pending translation requests. 


simpleWS


Any post-processing of the translated text (e.g. applying naming conventions or invoking further processing steps) should be done in the client callback handler which is called by eTranslation server. eTranslation is  a generic Translation Service. As such, it does not implement any client specific logic in terms of naming conventions or bespoke translation files. Because such requirements are known only by the client, any such post-processing operations needs to be perform by the client service.

All requests for translation will be handled by a single Web Service, called SecuredWSEndpointHandlerService.

This can be called from any computer language. Here are some examples for common languages:


Using eTranslation to make your website multilingual


To make this as user-friendly as possible, please check our guidelines.

Accessing the web service


To obtain the credentials needed to access the service:

If you are an EU staff member: DGT-MT@ec.europa.eu

If you work for an EU Member State public administration: help@cefat-tools-services.eu


SecuredWSEndPointHandlerService 


You can access the eTranslation web service service at: https://webgate.ec.europa.eu/etranslation/si/SecuredWSEndpointHandlerService?WSDL.

If you are registered to use the separate and secure Testa network,  you can use https://webgate.ec.testa.eu/etranslation/si/SecuredWSEndpointHandlerService?WSDL.

The entry point of the service conforms to the SOAP protocol. The web service uses Digest access authentication. The service contract (WSDL) address is reachable without authentication.


It is a good idea to carry out some initial tests of translation requests using the SOAP UI tool available here: https://www.soapui.org/

If you are unfamiliar with this tool, see https://www.soapui.org/soap-and-wsdl/getting-started.html for basic instructions.

ngrok cannot be used - as a virtual tunnel it is considered a potential security risk.


The structure of the XML message to send a request is below. Note that for Digest authentication, the password is passed in the header, not in the body of the request.

Sample translation request for a a text snippet :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cef="http://cef.dgt.ec.europa.eu">
   <soapenv:Header/>
   <soapenv:Body>
      <cef:translate>
         <arg0>
			<!--Optional:-->
            <external-reference>clientRequestId</external-reference>
            <caller-information>
               <application>CLIENT_APPLICATION_NAME</application>
	  		   <!--Optional:-->
               <username>toto</username>
	  		   <!--Optional:-->
               <institution>eu.europa.ec</institution>
			   <!--Optional:-->
               <department-number>DGT.R.3.002</department-number>
            </caller-information>            
            <text-to-translate>Hello World!</text-to-translate>
            <source-language>DE</source-language>
            <target-languages>
               <!--Zero or more repetitions:-->
               <target-language>EN</target-language>
			   <target-language>FR</target-language>
            </target-languages>
            <domain>SPD</domain>    
			<!--Optional:-->
            <requester-callback>http://my-client-server/my-client-context/my-success-handler</requester-callback>
			<!--Optional:-->
            <error-callback>http://my-client-server/my-client-context/my-error-handler</error-callback>
            <destinations>
               <!--Zero or more repetitions:-->
               <email-destination>toto@ec.europa.eu</email-destination>
               <!--Zero or more repetitions:-->
               <http-destination>http://my-client-server/my-client-context/</http-destination>
               <!--Zero or more repetitions:-->
               <ftp-destination>ftp://user:password@ftp_server_name:2021/mycallback/</ftp-destination>
               <!--Zero or more repetitions:-->
               <sftp-destination>sftp://user:password@sftp_server_name:2021/mycallback/</sftp-destination>
            </destinations>
         </arg0>
      </cef:translate>
   </soapenv:Body>
</soapenv:Envelope>


Sample translation request for a FTP or SFTP reference to a document  :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cef="http://cef.dgt.ec.europa.eu">
   <soapenv:Header/>
   <soapenv:Body>
      <cef:translate>
         <arg0>
			<!--Optional:-->
            <external-reference>clientRequestId</external-reference>
            <caller-information>
               <application>CLIENT_APPLICATION_NAME</application>
               <username>toto</username>
	  		   <!--Optional:-->
               <institution>eu.europa.ec</institution>
			   <!--Optional:-->
               <department-number>DGT.R.3.002</department-number>
            </caller-information>            
            <document-to-translate-path>ftp://user:pass@server:port/path...../file.doc</document-to-translate-path>
            <source-language>DE</source-language>
            <target-languages>
               <!--Zero or more repetitions:-->
               <target-language>EN</target-language>
			   <target-language>FR</target-language>
            </target-languages>
            <domain>SPD</domain>    
			<!--Optional:-->
            <requester-callback>http://my-client-server/my-client-context/my-success-handler</requester-callback>
			<!--Optional:-->
            <error-callback>http://my-client-server/my-client-context/my-error-handler</error-callback>
            <destinations>
               <!--Zero or more repetitions:-->
               <email-destination>toto@ec.europa.eu</email-destination>
               <!--Zero or more repetitions:-->
               <http-destination>http://my-client-server/my-client-context/</http-destination>
               <!--Zero or more repetitions:-->
               <ftp-destination>ftp://user:password@ftp_server_name:2021/mycallback/</ftp-destination>
               <!--Zero or more repetitions:-->
               <sftp-destination>sftp://user:password@sftp_server_name:2021/mycallback/</sftp-destination>
            </destinations>
         </arg0>
      </cef:translate>
   </soapenv:Body>
</soapenv:Envelope>
        


Sample translation request for a base64 encoded document in the request body:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cef="http://cef.dgt.ec.europa.eu">
   <soapenv:Header/>
   <soapenv:Body>
      <cef:translate>
         <arg0>
			<!--Optional:-->
            <external-reference>clientRequestId</external-reference>
            <caller-information>
               <application>CLIENT_APPLICATION_NAME</application>
               <username>toto</username>
	  		   <!--Optional:-->
               <institution>eu.europa.ec</institution>
			   <!--Optional:-->
               <department-number>DGT.R.3.002</department-number>
            </caller-information>            
            <document-to-translate-base64>
               <content>0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAOwADAP7/CQAGAAAAAAAAAAAAAAABAAAAEAAAAAAAAAAA
						EAAAAgAAAAEAAAD+////AAAAAAAAAAD/////////////////////////////////////////////
						AGkAbwBuAAAAAAAAAAAAAAA4AAIA////////////////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
						....
						AAAAAAAAAAAAAAAAXwAAAHQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
						AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///////////////8AAAAAAAAAAAAA
						AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD+////AAAAAAAAAAA=
			   </content>
               <format>doc</format>              
               <file-name>myfile</file-name>
            </document-to-translate-base64>
            <source-language>DE</source-language>
            <target-languages>
               <!--Zero or more repetitions:-->
               <target-language>EN</target-language>
			   <target-language>FR</target-language>
            </target-languages>
            <domain>SPD</domain>    
			<!--Optional:-->
            <requester-callback>http://my-client-server/my-client-context/my-success-handler</requester-callback>
			<!--Optional:-->
            <error-callback>http://my-client-server/my-client-context/my-error-handler</error-callback>
            <destinations>
               <!--Zero or more repetitions:-->
               <email-destination>toto@ec.europa.eu</email-destination>
               <!--Zero or more repetitions:-->
               <http-destination>http://my-client-server/my-client-context/</http-destination>
               <!--Zero or more repetitions:-->
               <ftp-destination>ftp://user:password@ftp_server_name:2021/mycallback/</ftp-destination>
               <!--Zero or more repetitions:-->
               <sftp-destination>sftp://user:password@sftp_server_name:2021/mycallback/</sftp-destination>
            </destinations>
         </arg0>
      </cef:translate>
   </soapenv:Body>
</soapenv:Envelope>
        


If you wish to avoid using an ftp server, one approach would be to:

1) Submit the document in the content parameter of the request in base64.

2) Specify an http destination in the list  <destinations>.

The translation will be included in the request body of the HTTP call, as base64 encoded content.


Definition of Parameters:

  • text-to-translate: the text to translate (maximum: 5000 characters).

For text snippet requests, the translated text will be provided directly in the requester-callback response if specified

  • document-to-translate-path : the FTP or SFTP path of the document to translate

Example: ftp://user:password@ftp_server_name:21/mypath/myfile.doc

  • document-to-translate-base64 : contains two mandatory and one optional tag which are described below:
    1. content: base 64 content
    2. format: format of the document. Accepted format are odt, ods,odp,odg, ott, ots, otp, otg, rtf, doc, docx, xls, xlsx, ppt, ppts, pdf, txt, htm, html, xhtml, xml, xlf, xliff, sdlxliff, tmx, rdf
    3. file-name: (optional) File name of the translated document without extension. It will be suffix by an underscore en target language ISO code in uppercase - dot - chosen output format.

Example: 

<document-to-translate-base64>
               <content>0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAOwADAP7/CQAGAAAAAAAAAAAAAAABAAAAEAAAAAAAAAAA
						EAAAAgAAAAEAAAD+////AAAAAAAAAAD/////////////////////////////////////////////
						AGkAbwBuAAAAAAAAAAAAAAA4AAIA////////////////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
						....
						AAAAAAAAAAAAAAAAXwAAAHQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
						AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///////////////8AAAAAAAAAAAAA
						AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD+////AAAAAAAAAAA=
			   </content>
               <format>doc</format>              
  			   <file-name>myfile</file-name>
</document-to-translate-base64>

text-to-translate or document-to-translate-path and document-to-translate-base64 are mutually exclusive. If text-to-translate is filled the former two tags cannot be sent. Doing so will generate a validation error.


  • external-reference: optional - external request ID. This parameter is the unique identifier of the request as defined by the client application. It can be set to any value by the calling application.

Example: 123456789

  • requester-callback: optional - This parameter specifies the URL that will be called at the end of the translation process when the translation has finished successfully. This URL is called with the HTTP POST method. 
    The following parameters will be included in the POST request in the query string:
    • target-language: If the original request contained more than one target language, this parameter is set to the language of the delivered document. The callback URL will be called once for each target language in the request.
    • translated-text (optional): Translated text in the case of text snippet request.
    • request-id: the request id
    • external-reference (optional): if the external reference was provided into the initial request

requester-callback can also be a FTP or SFTP file address. In this case, a new file will be created which contains the previous four parameters in JSON format. The file will be delivered to the FTP address specified.

Examplehttp://my-client-server/my-client-context/my-success-handler?my_own_requestID=123456789

Example : ftp://user:password@ftp_server_name:2021/mycallback/

  • error-callback: optional - This parameter specifies the URL that will be called in case an error occurred during the translation process. 
    This URL can be an HTTP address. In this case, this URL is called with the HTTP POST method. 
    The following parameters will be included in the POST request as key/value pair in the body:
    • error-code: Numeric code of the error.
    • error-message: The description of the error.
    • target-languages: Target language codes of the failed translation process.
    • request-id: the eTranslation request id
    • external-reference (optional): if the external reference was provided into the initial request

error-callback can also be an FTP or SFTP file address. In this case, a new file will be created which contains the previous five parameters in JSON format. The file will be delivered to the FTP address specified.

Example : http://my-client-server/my-client-context/my-success-handler?my_own_requestID=123456789

Example : ftp://user:password@ftp_server_name:2021/mycallback/

Example : EN

Example (list for more than one target language) :

<target-language>FR</target-language>

<target-language>DE</target-language>

<target-language>IT</target-language>

<target-language>FI</target-language>


  • caller-information: contains two mandatory tags and two optional described below:
    1. application: Required for authentication. Name of the client application. This parameter is used by the service to check if the application is an allowed client. Any application name needs to be authorized by the CEF service before it can be used.
    2. username: any name specified by the client system for its users. This is free text that can be used to specify individual users of client applications.
    3. institution: (Optional) parameter used to monitor the translation request. The parameter must be an institution's domain name as identified in EU Login (usually the email domain in reverse order). 

    4. department-number : (Optional) parameter used to monitor the translation request. It may be the department number of the connected user.

Example: 

<caller-information>
	<application>MY_APPLICATION_THAT_USES_THE_eTranslation_SERVICE</application>
	<username>toto</username>
	<!--Optional:-->
	<institution>eu.europa.ec</institution>
	<!--Optional:-->
	<department-number>DGT.R.3.4</department-number>
</caller-information>

If you do not have a dedicated application name and password, or for assistance with access rights, please contact the eTranslation team at the email addresses specified at the beginning of this document.

  • domain (optional): this makes it possible to choose translation engines that are tailored for certain subjects.

    Currently available domains are described here.

Example: SPD

  • output-format (optional) : Used only for document translation (document-to-translate-path or document-to-translate-base64 parameter specified). File extension of the translated file. If not specified, translated files will have the same format as the input document. Note that sdlxliff is not supported as an output format due to its proprietary nature. You can request xliff instead.

Example: doc

  • with-quality-estimate (optional) : Used to request an Excel (.xlsx file) containing the source segment, target segment and a quality estimate value for each segment. Boolean, so may be true, false, 0 or 1. If the quality estimate is requested, the output format parameter must be blank or set to 'xlsx'. This option is unavailable if text-to-translate parameter is specified.

Examples: false

  • destinations (optional if "text-to-translate" is present, mandatory for "document-to-translate-path" or "document-to-translate-base64"): Clients can choose from four methods of delivery to receive their translations:
    1. email-destination (0 or unlimited repetition): the email address where the eTranslation server will send the translated text snippet or document to the client.
    2. http-destination (0 to 5 repetitions) : the http URL to be called by the eTranslation server. Please note the translation will be encoded in base 64 will be attached to the request body, or plain text if original request is a text snippet. This also support https.
    3. ftp-destination (0 to 5 repetitions):  the ftp address where will be put the translation. The destination must be an ftp directory. The "/" at the end is optional. If the folder does not exist on the ftp address a new one will be created.

    4. sftp-destination (0 to 5 repetitions) : the sftp address where will be put the translation. The destination must be an sftp directory. The "/" at the end is optional. If the folder doesn't exist on the sftp address a new one will be created.

Example: 

<destinations>
    <email-destination>toto@ec.europa.eu</email-destination>
    <http-destination>http://my-client-server/my-client-context/</http-destination>
    <ftp-destination>ftp://user:password@ftp_server_name:2021/mydestination/</ftp-destination>
    <sftp-destination>sftp://user:password@sftp_server_name:2021/mydestination/</sftp-destination>
</destinations>

Secured Web Services (SOAP and REST)


When accessing the web service, the <application> parameter needs to be in the body of the request and the < password > needs to be passed in the authentication request header.

A simple way to test connectivity is to use SOAP-UI. Authentication information needs to be entered in the "Auth" tab, and then the request can be sent. The SOAP UI interfaces identifies the parameters somewhat differently from a direct call. Here, "username" is eTranslation's <application> parameter. The password is the one provided by the eTranslation team.

.

When the request is sent, the following logs are displayed in the "http logs" tab.

  • Fri Jan 19 14:21:52 CET 2018:DEBUG:>> "POST /etranslation/si/SecuredWSEndpointHandlerService HTTP/1.1[\r][\n]"
  • Fri Jan 19 14:21:52 CET 2018:DEBUG:<< "HTTP/1.1 401 Unauthorized[\r][\n]"
  • Fri Jan 19 14:21:52 CET 2018:DEBUG:<< "WWW-Authenticate: Digest realm="Contacts Realm via Digest Authentication", qop="auth", nonce="MTUxNjM2ODQxMjg2NTphYTEzYWViNjJjZWZjY2EyNGMzNzQ3YzNhMDQxZGM2MA=="[\r][\n]"
  • ------------
  • Fri Jan 19 14:21:52 CET 2018:DEBUG:>> "POST /etranslation/si/SecuredWSEndpointHandlerService HTTP/1.1[\r][\n]"
  • Fri Jan 19 14:21:52 CET 2018:DEBUG:<< "HTTP/1.1 200 OK[\r][\n]"

The initial call is not accepted, but is subsequently authenticated with the nonce.

Sample SOAP call

This example shows how to call the secured web service with Java :

public static long callWS(Translate translate) {
		String login = ..... ;
		String password = ..... ;
		WebServiceTemplate template = new WebServiceTemplate();
	    try {	       
	    	Jaxb2Marshaller marshaller = new Jaxb2Marshaller();	    	
			marshaller.setContextPath("eu.europa.ec.dgt.cef.core.model.generated");		
		 	
	        template.setMarshaller(marshaller); 
	        template.setUnmarshaller(marshaller);	     
	        template.setDefaultUri(URI);      
	        
	        Credentials credentials = new UsernamePasswordCredentials(login, password);
	        HttpComponentsMessageSender sender = new HttpComponentsMessageSender();
	        sender.setCredentials(credentials);
	        sender.afterPropertiesSet();
	        template.setMessageSender(sender);
	        JAXBElement<TranslateResponse> response = (JAXBElement<TranslateResponse>) template.marshalSendAndReceive(URI, translate);	       
	        return response.getValue().getReturn();
	    } catch (Exception e) {
	       e.printStackTrace();
	    }
	    return -1;	
	}

RESTful Secured Web Service


eTranslation exposes a secured RESTful web service available at this address: https://webgate.ec.europa.eu/etranslation/si/translate.

Authentication follows the approach taken for the SOAP web service.

The RESTful service must be called using POST, and the request body must 

contain the translation request as JSON format.

Not all destinations are required. For snippets, the translated text is returned in the requesterCallback parameter.

Callbacks encode parameters as a queryparameter string which are included as the body of the POST call.


For testing we again recommend SOAP UI.
POSTMAN fails because it does not handle DIGEST authentication properly.

Sample translation request for a a text snippet :

{
       "externalReference" : "123",
       "callerInformation" : {
              "application" : .....,
              "username" : .....
       },
       "textToTranslate" : "This is a small house",
       "sourceLanguage" : "EN",
       "targetLanguages" : [ "FR", "DE" ],
       "domain" : "SPD",
       "requesterCallback" : "http://my-client-server/my-client-context/my-success-handler",
	   "errorCallback" : "http://my-client-server/my-client-context/my-error-handler",      
       "destinations" : {
               "httpDestinations" : ["http://my-client-server/my-client-context/"],          
               "ftpDestinations" : ["ftp://user:password@ftp_server_name:2021/mycallback/"],
               "sftpDestinations" : ["sftp://user:password@sftp_server_name:2021/mycallback/"],
               "emailDestinations" : ["toto@ec.europa.eu"]
       }
}  

Sample translation request for a FTP or SFTP reference to a document  :

{
       "externalReference" : "123",
       "callerInformation" : {
              "application" : .....,
              "username" : .....
       },
       "documentToTranslatePath" : "ftp://user:pass@server:port/path...../file.doc",
       "sourceLanguage" : "EN",
       "targetLanguages" : [ "FR", "DE" ],
       "domain" : "SPD",
       "requesterCallback" : "http://my-client-server/my-client-context/my-success-handler",      
	   "errorCallback" : "http://my-client-server/my-client-context/my-error-handler",      
       "destinations" : {
               "httpDestinations" : ["http://my-client-server/my-client-context/"],          
               "ftpDestinations" : ["ftp://user:password@ftp_server_name:2021/mycallback/"],
               "sftpDestinations" : ["sftp://user:password@sftp_server_name:2021/mycallback/"],
               "emailDestinations" : ["toto@ec.europa.eu"]
       } 
      
       
}



Sample translation request for base64 encoded document in attachment :

{
       "externalReference" : "123",
       "callerInformation" : {
              "application" : .....,
              "username" : .....
       },
       "documentToTranslateBase64" : {
              "content" : "0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAOwADAP7/CQAGAAAAAAAAAAAAAAABAAAAEAAAAAAAAAAA
EAAAAgAAAAEAAAD+////AAAAAAAAAAD/////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
......
cgBkAEQAbwBjAHUAbQBlAG4AdAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAGgACAP///////////////wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACYA
AAAkDgAAAAAAAAUARABvAGMAdQBtAGUAbgB0AFMAdQBtAG0AYQByAHkASQBuAGYAbwByAG0AYQB0
AGkAbwBuAAAAAAAAAAAAAAA4AAIA////////////////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAXwAAAHQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///////////////8AAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD+////AAAAAAAAAAA=",
              "format" : "doc",
              "fileName" : "out" 
       },
       "sourceLanguage" : "EN",
       "targetLanguages" : [ "FR", "DE" ],
       "domain" : "SPD",
       "requesterCallback" : "http://my-client-server/my-client-context/my-success-handler",
	   "errorCallback" : "http://my-client-server/my-client-context/my-error-handler",      
       "destinations" : {
               "httpDestinations" : ["http://my-client-server/my-client-context/"],          
               "ftpDestinations" : ["ftp://user:password@ftp_server_name:2021/mycallback/"],
               "sftpDestinations" : ["sftp://user:password@sftp_server_name:2021/mycallback/"],
               "emailDestinations" : ["toto@ec.europa.eu"]
       }
}              


Sample REST call (Java)


// Import for HttpClient 4.*

import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.params.HttpClientParams;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.json.JSONArray;
import org.json.JSONObject;

// Import for HttpClient 5.0

import org.apache.hc.client5.http.auth.AuthScope;
import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.classic.methods.HttpPost;
import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
import org.apache.hc.core5.http.ClassicHttpResponse;
import org.apache.hc.core5.http.ContentType;
import org.apache.hc.core5.http.ParseException;
import org.apache.hc.core5.http.io.entity.EntityUtils;
import org.apache.hc.core5.http.io.entity.StringEntity;

public class Test {
	
	private static String createTranslationRequest(String fileName, String sourceLanguage) {
		JSONObject json = new JSONObject();
		JSONObject jsonCaller = new JSONObject();

		json.put("priority", 1);
		json.put("externalReference", "123");

		jsonCaller.put("application", "SOAP_UI");
		jsonCaller.put("username", "toto");
		json.put("callerInformation", jsonCaller);
		json.put("textToTranslate", "this is a test");
		json.put("sourceLanguage", sourceLanguage);

		JSONArray targetLanguages = new JSONArray();
		targetLanguages.add("FR");
		json.put("targetLanguages", targetLanguages);
		json.put("domain", "SPD");

		System.out.println(json.toString());

		return json.toString();

	}	
	
	
	// Call eTranslation with HttpClient version 4.*
	public static void main(String[] args) {
		try {
			String url = "https://webgate.ec.europa.eu/etranslation/si/translate";
			String userName = "*****";
			String password = "*****";

			HttpClientBuilder builder = HttpClientBuilder.create();
			CredentialsProvider provider = new BasicCredentialsProvider();
			AuthScope scope = new AuthScope(AuthScope.ANY);
			UsernamePasswordCredentials credentials = new UsernamePasswordCredentials(userName, password);
			provider.setCredentials(scope, credentials);
			builder.setDefaultCredentialsProvider(provider);

			HttpClient client = builder.build();

			HttpPost post = new HttpPost(url);
			post.setEntity(new StringEntity(createTranslationRequest(null, "EN"), ContentType.APPLICATION_JSON));

			HttpResponse response = client.execute(post);
			System.out.println(response.getStatusLine().getStatusCode());
		} catch (Exception e) {
			e.printStackTrace();
		}
	}

	// Call eTranslation with HttpClient version 5.0
    public static void main(String[] args) {
        try {
        	String url = "https://webgate.ec.europa.eu/etranslation/si/translate";
            String userName = "*****";
            String password = "*****";
 
            HttpClientBuilder builder = HttpClientBuilder.create();
            BasicCredentialsProvider credentialsProvider = new BasicCredentialsProvider();         
            UsernamePasswordCredentials credentials = new UsernamePasswordCredentials(userName, password.toCharArray());
          
            credentialsProvider.setCredentials(new AuthScope("webgate.ec.europa.eu", 443), credentials);
            builder.setDefaultCredentialsProvider(credentialsProvider);
 
            HttpClient client = builder.build(); 
            HttpPost post = new HttpPost(url);
            post.setEntity(new StringEntity(BODY, ContentType.APPLICATION_JSON));
 
            ClassicHttpResponse  response = (ClassicHttpResponse) client.execute(post);
            System.out.println(response.getCode());
            String responseJSON = EntityUtils.toString(response.getEntity(), Charset.forName("UTF-8"));
            System.out.println("Request Id : " + responseJSON);
        }
        catch (IOException e) { System.out.println(e); } catch (ParseException e) {
			e.printStackTrace();
		}
    }

}


Fair use and quotas:

Measures are in place to ensure fair use. Clients are expected to control the flow of their submissions so as not to violate these measures.

The limits take the firm of a concurrency quota.

Any client is able to submit up to the following at the same time:

  • 250 documents
  • 500 text snippets


When these limits are exceeded, requests will be rejected with a -20028 error (Concurrency quota exceeded). Requests will continue to be rejected until the number of submissions from the client in question drops below the upper limit.

Error codes : 

The below list displays all error codes and their description which the client could receive synchronously in case the request is invalid. Please note the error code is a negative number. We choose to do that to make the difference between valid request which is a positive number and invalid request which is a negative number.

-20000Source language not specified
-20001Invalid source language
-20002Target language(s) not specified
-20003Invalid target language(s)
-20004DEPRECATED
-20005Caller information not specified
-20006Missing application name
-20007Application not authorized to access the service
-20008Bad format for ftp address
-20009Bad format for sftp address
-20010Bad format for http address
-20011Bad format for email address
-20012Translation request must be text type, document path type or document base64 type and not several at a time
-20013Language pair not supported by the domain
-20014Username parameter not specified
-20015Extension invalid compared to the MIME type
-20016DEPRECATED
-20017Username parameter too long
-20018Invalid output format
-20019Institution parameter too long
-20020Department number too long
-20021Text to translate too long
-20022Too many FTP destinations
-20023Too many SFTP destinations
-20024Too many HTTP destinations
-20025Missing destination
-20026Bad requester callback protocol
-20027Bad error callback protocol
-20028Concurrency quota exceeded
-20029Document format not supported
-20030Text to translate is empty
-20031Missing text or document to translate
-20032Email address too long
-20033Cannot read stream
-20034Output format not supported
-20035Email destination tag is missing or empty
-20036HTTP destination tag is missing or empty
-20037FTP destination tag is missing or empty
-20038SFTP destination tag is missing or empty
-20039Document to translate tag is missing or empty
-20040Format tag is missing or empty
-20041The content is missing or empty
-20042

Source language defined in TMX file differs from request

-20043

Source language defined in XLIFF file differs from request

-20044Output format is not available when quality estimate is requested. It should be blank or 'xslx'
-20045Quality estimate is not available for text snippet
-20046Document too big (>20Mb)
-20047Quality estimation not available
-40010Too many segments to translate
-80004

Cannot store notification file at specified FTP address

-80005Cannot store notification file at specified SFTP address
-80006Cannot store translated file at specified FTP address
-80007Cannot store translated file at specified SFTP address
-90000Cannot connect to FTP
-90001Cannot retrieve file at specified FTP address
-90002File not found at specified address on FTP
-90007Malformed FTP address
-90012Cannot retrieve file content on SFTP
-90013Cannot connect to SFTP
-90014Cannot store file at specified FTP address
-90015Cannot retrieve file content on SFTP
-90016Cannot retrieve file at specified SFTP address