iTranslate API

General information

iTranslate4 is an automatic tool which translates text from a language (the source language) to another (the target language). Employing several different machine translation providers iTranslate4 can provide several different translations for certain source and target languages which can help the user to understand the original text more easily.

This document describes the iTranslate4 API. It is intended for developers who want to integrate the iTranslate4 translation service into a website or want to access this service programmatically. The technical documentation provided here covers the specification of the interface through which your client program can communicate with the central iTranslate4 server. You need to implement this interface in order to use the iTranslate4 service.

Requests

Function calls are sent by the client to the iTranslate4 server as HTTP GET or POST requests. The generic request format is as follows:

http://itranslate4.eu/api/<function_name>?<parameters>

The name of the function to be used is part of the URL, function-specific options and data is to be sent as query parameters.

Function names and parameters for each function are described in iTranslate4 API functions.

Response data format

iTranslate4 HTTP responses are JSON objects. JSON (JavaScript Object Notation) is a common, text-based data interchange format which defines a simple set of rules for the portable representation of structured data.

Responses for each function are described in iTranslate4 API functions.

Authorization

To use the iTranslate4 service you must identify yourself with an authorization key in every request you send to the iTranslate4 server. The authorization key must be present as a HTTP parameter with parameter name auth. (See Example 1.)

An iTranslate4 authorization key for your application can be generated here.

Character Encoding

All data sent through the iTranslate4 API must be UTF-8 encoded. All data received through the iTranslate4 API is UTF-8 encoded.

Error Handling

Standard HTTP error codes are used to indicate error conditions.

code	standard name	example
400	Bad Request	e.g. invalid character code
403	Forbidden	e.g. invalid or exhausted authorization key
408	Request Timeout	translation could not be finished within given time interval
500	Internal Server Error	iTranslate4 server experiencing temporary technical difficulties
503	Service Unavailable	iTranslate4 server unavailable

Beside the above error codes the iTranslate4 server will attempt to send a JSON object with an err field containing an informative message about the error (See Example 1.)

Alternative translations

Depending on language, iTranslate4 service provides one or more different translations using different independent translation engines. iTranslate4 also uses indirect translation, i.e. translating the source text into an interlingua (e.g. English) and then translating this text again into the target language.

For each source language - target language pair there is a predefined translation route list, telling how the target language can be reached from the source language, both directly (using one translation service) or indirectly (using two translation services connected by an interlingua). The portion of translation route list to use can be defined and can also be customized (see Translate and GetRoutes functions).

Limitations

Size of the text to be translated is limited to 1000 characters.

iTranslate4 API functions

Valid functions, their purpose and associated data formats are listed below. Whether a parameter or JSON field is obligatory or not is indicated by REQUIRED and OPTIONAL, respectively.

The Translate function

The Translate function allows the client to send a block of text to the iTranslate4 server for translation using the specified language settings.

Call format

http://itranslate4.eu/api/Translate?<parameters>

Request parameters

auth:	[REQUIRED] The iTranslate4 authorization key.
src:	[REQUIRED] The IANA code of the source language. Available source languages can be obtained using the GetLanguages function.
trg:	[REQUIRED] The IANA code of the target language. Available target languages can be obtained using the GetLanguages function.
dat:	[REQUIRED] The text to be translated. Newlines are handled as paragraph separators. This parameter can be added multiple times to translate multiple independent texts. Size of the text (size of all dat parameters summarized) must be under the limit.
min:	[OPTIONAL] Minimum number of alternative translations required in the result. Default value is: 1. Depending on the language the result will contain at least min number of alternative translations.
max:	[OPTIONAL] Maximum number of alternative translations required in the result. Default value is: 1. Depending on the language the result will contain at most max alternative translations. The first max number of routes from the translation route list will be used.
timeout:	[OPTIONAL] Number of maximum seconds to wait for the reply. The translation waits until the min number of translation arrives or the timeout expires. The default value is: 20s.
dom:	[OPTIONAL] Domain or topic of the text to be translated. Our translation services may use specialized dictionaries depending on this setting. The list of allowed values and their meaning is defined in the following table. Default value is: general. general default behavior / no specialized dictionaries art arts & humanities and social sciences (art and culture, architecture, music and dance, literature and theatre, visual arts, humanities, education, history, linguistics, philosophy, psychology, work and social life, society and welfare, religion, politics, university, etc.) law law & administration (customs, criminality, quality assurance etc.) sci natural science (mathematics, physics, chemistry, geography) tech technology (engineering, construction, electrical engineering, power generation, environment, mechanical engineering, exploitation of raw materials, optics and photography, manufacturing, wood processing, productive industry, cars etc.) info information technology (informatics, computers, data processing etc.) tel telecommunication and media (tele industry, telephony, etc.) bio health and biology (pharmaceuticals, biology, food and nutrition science) eco economy and trade (finance, business, logistics etc.) agr agriculture travel transport and travelling (traffic, rail etc.) mil military (armament, naval, maritime etc.) sport sports & games (leisure activities, cooking etc.)
rid:	[OPTIONAL] Used for customizing the translation route list. Overwrites default (first) translation route. Can be added multiple times: first rid defines the first translation route, second rid defines the second translation route (eg: rid=sys.ts&rid=pro.ts...). The translation route list will consist of these routes (explicitly given by rids), followed by the other available translation routes in the original order. Available rids can be obtained using the GetRoutes function. (See also Alternative translations.)
frm:	[OPTIONAL] Used to define the input document format. If the input is treated as a "document", then the values of min and max are always 1, and multiple dat parameters are only concatenated (with an additional space) instead of treated as different inputs. The only supported document format is "html" for now. The default value is "text", which is not treated as a "document". (See also Response JSON object (document) on how the response changes.)
app:	[RECOMMENDED] Used to identify your application in the statistics. The value can contain english alphabet characters, numbers, underscores or hyphens.

Response JSON object (default format)

JSON key	required?	type
dat	REQUIRED	ARRAY of tr_obj

dat:	An array of the alternative translators’ response.

tr_obj

JSON key	required?	type
rid	REQUIRED	STRING
text	OPTIONAL	ARRAY of STRING
err	OPTIONAL	STRING
length	REQUIRED	NUMBER

rid:	Identifies the translation route used to create this translation. (See also the GetRoutes function.)
text:	Each element of the array represents the result for one dat parameter. If err is not included or is 0 then this item is REQUIRED.
err:	The error codes and descriptions sent back from the translators. The format is: "<number> <description>"
length:	The number of translated characters.

Response JSON object (document)

Response is a JSON ARRAY of trd_obj. Each element specifies a translated chunk.

trd_obj

JSON key	required?	type
dat	REQUIRED	STRING
rid	REQUIRED	STRING
cnt	REQUIRED	NUMBER
sum	OPTIONAL	NUMBER
err	OPTIONAL	STRING
length	REQUIRED	NUMBER

dat:	Part of the translated document to be concatenated with the other dat elements in the trd_objs. If err is included and is not 0 then this item contains the original part of the document.
rid:	Identifies the translation route used to create this translation. (See also the GetRoutes function.)
cnt:	The number of this chunk.
sum:	The number of the chunks in this document.
err:	The error codes and descriptions sent back from the translators. The format is: "<number> <description>"
length:	The number of translated characters.

Example 1

Translating two texts from German to English can be accessed this way:

Request (client → iTranslate4 server):

http://itranslate4.eu/api/Translate?auth=<AUTH_KEY>&src=de&trg=en
&dat=Andreas+hat+seine+Aufgabe+erledigt.&dat=Er+kann+jetzt+nach+Hause+gehen.

Response JSON object (iTranslate4 server → client):

{
	"dat":
	[
		{
			"rid":"pro.ts",
			"text":
			[
				"Andreas has done his job.",
				"Now he can go home."
			]
		},
		{
			"rid":"tmp.ts",
			"err":"500 service under maintenance"
		}
	]
}

Example 2

Translating a simple html formatted paragraph from German to English can be done this way:

Request (client → iTranslate4 server):

http://itranslate4.eu/api/Translate?auth=<AUTH_KEY>&src=de&trg=en
&dat=%3Cp%3EIch+bin+%3Cu%3Eunterstrichen%3C%2Fu%3E%3C%2Fp%3E.

Response JSON object (iTranslate4 server → client):

[
	{
		"dat":"<p>I am <u>underlined.</u></p>",
		"rid":"pro.ts",
		"cnt":1,
		"sum":1,
		"length":16
	}
]

The GetLanguages function

This function provides information about available source and target languages. These languages are valid options as src and trg parameters in Translate function.

Call format

http://itranslate4.eu/api/GetLanguages?<parameters>

Request parameters

auth:

[REQUIRED] The iTranslate4 authorization key.

Response JSON object

JSON key	required?	type
src	REQUIRED	ARRAY of STRING
trg	REQUIRED	ARRAY of STRING
exclude	REQUIRED	ARRAY of ARRAY of STRING

src:	An array of the available source languages in IANA language code format.
trg:	An array of the available target languages in IANA language code format.
exclude:	An array of the language pairs in [<src>,<trg>] format for which there are no routes at the moment.

Example

Lists of available source and target languages can be obtained this way:

Request (client → iTranslate4 server):

http://itranslate4.eu/api/GetLanguages?auth=<AUTH_KEY>

Response JSON object (iTranslate4 server → client):

{
	"src":
	[
		"ar","bg","br","ca","cs","cy","da","de",
		"el","en","eo","es","eu","fa","fi","fr",
		"gl","hi","hr","hu","is","it","ja","kk",
		"ko","lv","mk","nl","nn","no","oc","pl",
		"prs","ps","pt","ro","ru","sl","sq","sr",
		"sv","tg","tr","uk","ur","zh"
	],
	"trg":
	[
		"ar","bg","ca","da","de","el","en","eo",
		"es","fi","fr","gl","hu","it","ja","kk",
		"ko","lv","mk","nl","nn","no","oc","pl",
		"pt","ro","ru","sl","sv","tr","uk","zh"
	],
	"exclude":
	[]
}

The GetRoutes function

This function provides information about the available alternative translations returning the translation route list for a given language pair. This list consists of route IDs which are valid options as rid parameter in Translate function. (Learn more about Alternative translations.)

Call format

http://itranslate4.eu/api/GetRoutes?<parameters>

Request parameters

auth:	[REQUIRED] The iTranslate4 authorization key.
src:	[REQUIRED] The IANA code of the source language.
trg:	[REQUIRED] The IANA code of the target language.

Response JSON object

Response is a JSON ARRAY of STRING. Each element specifies a valid route ID.

Example

List of available translation routes for Polish to Russian can be obtained this way:

Request (client → iTranslate4 server):

http://itranslate4.eu/api/GetRoutes?auth=<AUTH_KEY>&src=pl&trg=ru

Response JSON object (iTranslate4 server → client):

[
	"pwn.ts","trd.ts","sys.ts,en,pro.ts","sys.ts,en,trd.ts",
	"sys.ts,en,sys.ts","pwn.ts,en,pro.ts","pwn.ts,en,trd.ts",
	"pwn.ts,en,sys.ts","trd.ts,en,pro.ts","trd.ts,en,sys.ts"
]

There are two kinds of translation routes (see also Alternative translations.) Direct translation routes consists of a simple provider ID (e.g. "pwn.ts"), while indirect translation routes consists of two provider IDs and an IANA language code in between ("sys.ts,en,pro.ts"), this language (English in this case) is used as interlingua. Provider names can also be queried using the GetProviders function.

The GetProviders function

This function tells the full name of the different machine translation providers (companies) which take part in the iTranslate4 service.

Call format

http://itranslate4.eu/api/GetProviders?<parameters>

Request parameters

auth:

[REQUIRED] The iTranslate4 authorization key.

Response JSON object

Response is a JSON object containing provider ID - provider name pairs.

Example

Full name of providers employed in iTranslate4 can be obtained this way:

Request (client → iTranslate4 server):

http://itranslate4.eu/api/GetProviders?auth=<AUTH_KEY>

Response JSON object (iTranslate4 server → client):

{
	"ame.ts":"Amebis","ape.ts":"Apertium","goo.ts":"Google",
	"grs.ts":"GrammarSoft","lgt.ts":"Linguatec","lin.ts":"Lingenio",
	"mor.ts":"MorphoLogic","mst.ts":"Microsoft","pro.ts":"PROMT",
	"pwn.ts":"pwn.pl Sp. z o.o.","sky.ts":"SkyCode","sun.ts":"Sunda",
	"sys.ts":"SYSTRAN","trd.ts":"Trident"
}

Migration to iTranslate4 API

This section describes how to switch to iTranslate4 API for former users of Google Translate API.

For users of Google Translate API v2: simply change the URL with the iTranslate4 authorization key to:

http://itranslate4.eu/api/Translate?auth=<AUTH_KEY>&mode=g2

Supported features: simple translation, and translating multiple inputs together. Supported parameters: source, target, q

For users of Google Translate API v1: simply change the URL with the iTranslate4 authorization key to:

http://itranslate4.eu/api/Translate?uid=<AUTH_KEY>&mode=g1

Supported features: simple translation, and translating multiple input's together. Supported parameters: langpair, q