The SVN url has been changed by SourceForge. In your repository root, or in an individual module, run the command:
svn switch --relocate https://apertium.svn.sourceforge.net/svnroot/apertium/ https://svn.code.sf.net/p/apertium/svn/

Apertium web service

From Apertium
Jump to: navigation, search

The ScaleMT API at api.apertium.org seems to be down currently, in the meanwhile you could try using Apy


Contents

[edit] Introduction

This page describes how to access the Apertium web service. This service allows you to add machine translation capabilities to your applications without installing Apertium. The Apertium web service is built upon ScaleMT, a scalable platform for building machine translation services. You can also become a web service provider by installing ScaleMT or other Apertium web service implementations (Apertium_services) on your own server.

IMPORTANT NOTICE: THIS SERVICE IS IN BETA STAGE

[edit] Get your own API Key

Apertium web service usage for unregistered applications is limited to a certain amount of requests per IP. If you want to overcome that restriction, please register and get an API key. This way we can track where our traffic come from. Registered applications enjoy a more generous traffic limit.

To register, please visit:

http://api.apertium.org/register.jsp

Once the registration process is finished, you will receive an API key that must be included in all the requests your application perform. If you forget your key, register again with the same email and url, and you will receive it by email.

[edit] Example

Here you can find one example of the type of applications that can be built using the Apertium API:

http://api.apertium.org/apiexample.html

It is a javascript web application (the source is included in the HTML page) that retrieves the last 10 messages written in English from Twitter and translates them into Spanish using the Apertium REST API (see the following section for details about the different Apertium APIs).

[edit] API Reference

We have designed different APIs for the different types of applications that need machine translation services.

For web applications, there is a REST API, that returns JSON data, and supports JSONP. This way, all the translation functionality can be moved to the client. Additionally, a JavaScript library makes the usage of the REST API even easier.

For desktop applications, there is a XML-RPC API.

These are only recommendations: you can freely choose which API to use for your application.

[edit] JSONP REST API

This API is very similar to Google AJAX Language API to make as easy as possible switching to Apertium JSONP REST API. For more information about Google AJAX Language API, see http://code.google.com/intl/en/apis/ajaxlanguage/documentation/reference.html#_intro_fonje .

Communication with the service is made by simply performing HTTP GET or HTTP POST requests with the appropriate arguments to one of the following URLs. The value of arguments must be properly escaped (e.g., via the Javascript's encodeURIComponent() method).

http://api.apertium.org/json/translate

and

http://api.apertium.org/json/listPairs

They return a JSON object. The first one translates pieces of plain text or html code, and the second one lists the available language pairs.


[edit] Common arguments and response format

These arguments are all optional and common to both resources:

  • key : User's personal API key. Requests from registered users have higher priority.
  • callback : Alters the response format, adding a call to a Javascript function. See description below.
  • context : If callback parameter is supplied too, adds additional arguments to the function call. See description below.

If nor callback neither context arguments are supplied, this is the JSON object returned by both resources:

{ "responseData" : JSON Object with the requested data , "responseStatus" : Response numeric code , "responseDetails" : Error description }

If callback argument is supplied, a call to a function named by the callback value is returned. For instance, if callback argument's value is foo, this is the JavaScript code returned:

foo({ "responseData" : JSON Object with the requested data , "responseStatus" : Response numeric code , "responseDetails" : Error description })

If both callback and context arguments are supplied, the returned function call has more arguments. If callback's value is foo and context's value is 'bar:

foo('bar',JSON Object with the requested data , Response numeric code , Error description )

[edit] listPairs resource

This resource only accepts the common arguments.

The response data returned is an array of language pairs, following this format:

[{"sourceLanguage": source language code ,"targetLanguage": target language code }, ... ]

responseStatus is always 200, that means the request was processed OK, and responseDetails has a null value.

So if we call this resource with no arguments:

curl 'http://api.apertium.org/json/listPairs'

we get, for example:

{"responseData":[{"sourceLanguage":"ca","targetLanguage":"oc"},{"sourceLanguage":"en","targetLanguage":"es"}],"responseDetails":null,"responseStatus":200}

[edit] translate resource

This resource accepts the common arguments mentioned above, plus the following specific arguments:

  • q : Source text or HTML code to be translated. Compulsory argument.
  • langpair : Source language code and target language code, separated by '|' character, which is escaped as '%7C'. Compulsory argument.
  • format : Source format. txt for plain text and html for HTML code. This argument is optional. If this argument is missing it is assumed that source is plain text.
  • markUnknown : yes for placing an asterisk next to each unknown word, no for not placing it. This argument is optional. If this argument is missing, an asterisk is placed next to each unknown word.

The response data is JSON object following this format:

{ "translatedText" : translated text }

Many different response status codes can be returned. This is the list with all the codes and their meaning:

  • 200 : Text has been translated successfully, responseDetails field is null.
  • 400 : Bad parameters. A compulsory argument is missing, or there is an argument with wrong format. A more accurate description can be found in responseDetails field.
  • 451 : Not supported pair. The translation engine can't translate with the requested language pair.
  • 452 : Not supported format. The translation engine doesn't recognize the requested format.
  • 500 : Unexpected error. An unexpected error happened. Depending on the error, a more accurate description can be found in responseDetails field.
  • 552 : The traffic limit for your IP or your user has been reached.

Here is a simple example. Requesting a translation with:

curl 'http://api.apertium.org/json/translate?q=hello%20world&langpair=en%7Ces&callback=foo'

the result is:

foo({"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200})

And if we add the context parameter:

curl 'http://api.apertium.org/json/translate?q=hello%20world&langpair=en%7Ces&callback=foo&context=a'

we get

foo('a',{"translatedText":"hola Mundo"},200,null)

[edit] Batch interface

More than one translation can be performed in the same request if we use more than one q argument or more than one langpair. If there is only one q argument and more than one langpair arguments, the same input string is translated with different language pairs. If there is only one langpair argument and more than one q arguments, the different input strings are translated with the same language pair. And if both arguments are supplied more than one time, and they are repeated exactly the same times, the first q is translated with the first langpair, the second q with the second langpair, etc.

The returned JSON changes a bit when using the batch interface. Now the field responseData contains an array of JSON objects, each one with the usual fields: responseData, responseStatus and responseDetails. Note that we have particular values of responseStatus and responseDetails for each translation, but global values too. If all the translation are OK, these values match, but if there is an error in any translation, global values of these fields take the value of the erroneous translation. If there is more than one erroneous translation, global fields take the value of one the the erroneous translations.

These examples show the described behavior:

curl  'http://api.apertium.org/json/translate?q=hello%20world&q=bye&langpair=en%7Ces'
{"responseData":[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"adiós"},"responseDetails":null,"responseStatus":200}],"responseDetails":null,"responseStatus":200}


curl  'http://api.apertium.org/json/translate?q=hello%20world&langpair=en%7Ces&langpair=en%7Cca&callback=foo'
foo({"responseData":[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"Món d'hola"},"responseDetails":null,"responseStatus":200}],"responseDetails":null,"responseStatus":200})


curl  'http://api.apertium.org/json/translate?q=hello%20world&q=goodbye&langpair=en%7Ces&langpair=en%7Cca&callback=foo&context=bar'
foo('bar',[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"adéu"},"responseDetails":null,"responseStatus":200}],200,null)

[edit] Javascript library

If you plan to use the JSON REST API from a Javascript client (that's the use the API is intended for), we have a Javascript library that will make that task easier. It is very similar to the Google AJAX Language API one:

http://code.google.com/intl/en/apis/ajaxlanguage/documentation/reference.html#GlobalMethods

To use it, firstly include the library code with:

<script type="text/javascript" src="http://api.apertium.org/JSLibrary.js?key=YOURAPIKEY"></script>

Replace YOURAPIKEY with the actual value of your API key. If you don't have an API key, it is not necessary to include the query parameter key.

It will import an object called apertium. These are the operations supported by this object:

Method Return type Description
apertium.translate(content,sourceLang,targetLang,callback) None Translates the given content. It is an asynchronous function: instead of directly returning the translation, the callback function is called when the translation is available.
  • content: Can be a simple string, which means that the source is treated as plain text, or an object with two fields:
    • type: the format of the text to be translated. Its values are defined in the object apertium.ContentType. Currently only plain text and HTML are supported.
    • text: simple string containing the text or html code to be translated.
  • sourceLang: Source language code, e.g. "es", "en", ...
  • targetLang: Target language code, e.g. "es", "en", ...
  • callback: Function to be called when the translation is available. It receives one argument: the translation result. It is an object with the following fields:
    • error. Optional field, only present if there has been any problem with the translation. It has two fields:
    • translation. The translation of the input text.
apertium.isTranslatablePair(sourceLang,targetLang) Boolean Returns true if the translation engine can translate the given language pair. Returns false otherwise. Arguments:
  • sourceLang: Source language code, e.g. "es", "en", ...
  • targetLang: Target language code, e.g. "es", "en", ...
apertium.isTranslatable(sourceLang) Boolean Returns true if the translation engine can translate from the given source language to any target language. Returns false otherwise. Arguments:
  • sourceLang: Source language code, e.g. "es", "en", ...
apertium.getSourceLanguages() Array Returns an array containing the language codes of all the supported source languages.
apertium.getTargetLanguages(sourceLang) Array Returns an array containing the language codes of all the target languages supported for the given source language.
  • sourceLang: Source language code, e.g. "es", "en", ...
apertium.getSupportedLanguagePairs() Array Returns an array containing the codes of all the supported language pairs. The array is made of objects. Each object contains the following fields:
  • source: Source language code, e.g. "es", "en", ...
  • target: Target language code, e.g. "es", "en", ...

Object apertium.ContentType:

apertium.ContentType = {
  'TEXT' : 'txt',
  'HTML' : 'html'
};

[edit] XML-RPC API

XML-RPC is a remote procedure call protocol which uses XML to encode its calls and HTTP as a transport mechanism. The (quite simple) specification can be browsed at http://www.xmlrpc.com/spec.

There are plenty of libraries for different programming languages that you can use to call the service:

http://en.wikipedia.org/wiki/XML-RPC#Implementations

To perform a remote call to the service, firstly you need to tell to the library which is the proxy URL (also known as endpoint). It is:

http://api.apertium.org/xmlrpc

Then you can call methods if you know the object that provides them and theirs name. The object name is:

service

And this is the list of supported methods:

Method Return type Description
service.translate(string text,string format,string sourceLang,string targetLang,[boolean markUnknown,]string key) string Returns the translation of the given text.
  • text: source text to be translated.
  • format: the format of the text to be translated. Use the value "txt" for plain text and "html" for HTML pages or fragments.
  • sourceLang: Source language code, e.g. "es", "en", ...
  • targetLang: Target language code, e.g. "es", "en", ...
  • markUnknown: 'true' for placing an asterisk next to each unknown word, 'false' for not placing it. This parameter is optional. If omitted, its default value is 'false'.
  • key: your API key. If you don't have an API key, use an empty string.

If there is any error, the standard XML-RPC error response is returned. See section Fault example from http://www.xmlrpc.com/spec . The error codes returned have the same meaning as the ones defined in ScaleMT#translate_resource.

service.translateDocument(base64 sourceDocument,string format,string sourceLang,string targetLang,[boolean markUnknown,]string key) base64 Returns the translation of the given document. This method is very similar to the previous one but intended to translate rtf and odt documents.
  • sourceDocument: document to be translated, treated as a binary file.
  • format: the format of the document to be translated. Use the value "odt" for ODT documents and "rtf" for RTF documents.
  • sourceLang: Source language code, e.g. "es", "en", ...
  • targetLang: Target language code, e.g. "es", "en", ...
  • markUnknown: 'true' for placing an asterisk next to each unknown word, 'false' for not placing it. This parameter is optional. If omitted, its default value is 'false'.
  • key: your API key. If you don't have an API key, use an empty string.

If there is any error, the standard XML-RPC error response is returned. See section Fault example from http://www.xmlrpc.com/spec . The error codes returned have the same meaning as the ones defined in ScaleMT#translate_resource.

service.getSupportedLanguagePairs() array Returns an array containing the codes of all the supported language pairs. The array is made of struct elements. Each struct contains the following fields:
  • sourceLanguage: Source language code, e.g. "es", "en", ...
  • targetLanguage: Target language code, e.g. "es", "en", ...

[edit] Examples

[edit] PHP

This example requires the library XMLRPC for PHP

<?php
	include("xmlrpc.inc");
	
        $c=new xmlrpc_client("/xmlrpc", "api.apertium.org");
	$f=new xmlrpcmsg('service.translate',array(new xmlrpcval("hola mundo"),new xmlrpcval("txt"),new xmlrpcval("es"),
new xmlrpcval("en"),new xmlrpcval(false,"boolean"),new xmlrpcval("YOURKEY")));
	$r=&$c->send($f);

	if(!$r->faultCode())
	{
		$v=$r->value();
		print htmlspecialchars($v->scalarval());
	}
?>

	include("xmlrpc.inc");
	
	$c=new xmlrpc_client("/xmlrpc", "api.apertium.org");
        $pairs = new xmlrpcmsg('service.getSupportedLanguagePairs');
	$r=&$c->send($pairs);

	$sourceTarget = array();

	for($i = 0; $i < sizeof($r->val->me['array']); $i++) {
		$sl = $r->val->me['array'][$i]->me['struct']['sourceLanguage']->me['string'];
		$tl = $r->val->me['array'][$i]->me['struct']['targetLanguage']->me['string'];

		$sourceTarget[$sl] = $tl;
	}

	foreach(array_keys($sourceTarget) as $k) {
		print  $k . '-' . $sourceTarget[$k] ;
	}

[edit] References

  • "ScaleMT: a free/open-source framework for building scalable machine translation web services". Víctor M. Sánchez-Cartagena, Juan Antonio Pérez-Ortiz. Open Source Tools for Machine Translation, MT Marathon 2010, Dublin, Ireland, 2010. The Prague Bulletin of Mathematical Linguistics 93, p. 97-106. [pdf]
  • "An open-source highly scalable web service architecture for the Apertium machine translation engine". Víctor M. Sánchez-Cartagena, Juan Antonio Pérez-Ortiz. First International Workshop on Free/Open-Source Rule-Based Machine Translation, Alicante, Spain, 2009, p. 51-58. [pdf]
Personal tools