| Method | Return Type | Description |
|---|---|---|
google.language.translate(text|option, srcLang, destLang, callback) |
None |
A global method that will return translated text for the given text supplied, matching the destination language. The result is supplied asynchronously to the given callback function as the result object.
|
google.language.detect(text, callback) |
None |
A global method that will return the language code that describes the language of the given text. The result is supplied asynchronously to the given callback function as the result object.
|
error?codemessagetranslationdetectedSourceLanguage? New!error?codemessagelanguageisReliableconfidenceThe google.language.Languages enumeration provides a mapping from name constants to language codes used as srcLang and destLang arguments to google.language.translate and as the result.language result for google.language.detect. These are the same codes that are used on Google Translate.
var google.language.Languages = {
'ENGLISH' : 'en',
'CHINESE' : 'zh',
'CHINESE_SIMPLIFIED' : 'zh-CN',
'CHINESE_TRADITIONAL' : 'zh-TW',
'ARABIC' : 'ar',
'FRENCH' : 'fr',
'GERMAN' : 'de',
'ITALIAN' : 'it',
'JAPANESE' : 'ja',
'KOREAN' : 'ko',
'PORTUGUESE' : 'pt-PT',
'RUSSIAN' : 'ru',
'SPANISH' : 'es',
'DUTCH': 'nl',
'UNKNOWN' : ''
};
The google.language.ContentType enumeration provides acceptable type values for the content type of the text to be translated. By default the system treats the text to be translated as HTML and will preserve the appropriate markup in the resulting translation.
var google.language.ContentType = {
'TEXT' : 'text',
'HTML' : 'html'
};
For Flash developers, and those developers that have a need to access the AJAX Language API from other Non-Javascript environments,
the API exposes a simple RESTful interface. In all cases, the method supported is GET and the response format is a
JSON encoded result with embedded status codes. Applications that use this interface must abide by
all existing terms of use. An area to pay special attention to relates to correctly identifying
yourself in your requests. Applications MUST always include a valid and accurate http referer header
in their requests. In addition, we ask, but do not require, that each request contains a valid API Key. By providing a key, your application
provides us with a secondary identification mechanism that is useful should we need to contact you in order to correct any problems.
Like the core Javascript interface, this interface is exposed through a uniform URL containing a mix of both standard, and method specific CGI arguments. Your application can use an http stack of it's choosing. The only requirement is that you must be able to construct a properly constructed URL with all necessary cgi arguments, that you send an http referer header that accurately identifies your application, and that you are able to process the JSON encoded response.
Each Language API method is accessed through a standard URL. The following table lists the URL used to access each method.
| Searcher | Base Url |
|---|---|
| Translate Language | http://ajax.googleapis.com/ajax/services/language/translate |
| Detect Language | http://ajax.googleapis.com/ajax/services/language/detect |
Each request contains a mix of standard URL arguments as well as an optional set of method specific arguments. This section
describes the standard arguments that are uniform accross all methods and that convey virtually identical semantic information
to each method. In some cases, an argument is optional. This is indicated with a ? following the name of the argument.
In all cases, the value of a CGI argument must be properly escaped (e.g., via the functional equivalent of
Javascript's encodeURIComponent() method).
The following table lists the standard URL arguments. Additional sections, appear below that highlight method specific arguments.
| Argument | Example | Description |
|---|---|---|
| q | q=Hello%World |
This argument supplies the query term passed to the method. For the translate method, this argument supplies the text to translate. For the
detect methods the value is the text to detect the language of.
|
| v | v=1.0 |
This argument supplies protocol version number. The only valid value at this point in time is 1.0
|
| hl? | hl=fr |
This optional argument supplies the host language of the application making the request. If this argument is not present then
the system will choose a value based on the value of the Accept-Language http header. If this header
is not present, a value of en is assumed.
|
| key? | key=your-key | This optional argument supplies the application's key. If specified, it must be a valid key associated with your site which is validated against the passed referer header. The advantage of supplying a key is so that we can identify and contact you should something go wrong with your application. Without a key, we will still take the same appropriate measures on our side, but we will not be able to contact you. It is definitely best for you to pass a key. |
| callback? | callback=foo |
This optional argument alters the standard response format. When supplied, instead of producing a simple JSON encoded object,
the system produces a Javascript function call response where the value of callback specifies the name of the function
called in the response. When this argument is supplied, applications must also supply the context argument. The function
call signature is:
callbackFunction(
contextValue, // the context arg value
responseObject, // the method result
responseStatus, // 200 on success, non-200 on failure
errorDetails) // error string for non-200 response
|
| context? | context=bar |
This optional argument is related to the context argument. When both are supplied, the value of context is
passed as the first argument to the function call response. E.g., a request containing &callback=foo&context=bar generates
a function call response of:
foo("bar", responseObject, responseStatus, errorDetails)
|
As discussed briefly in the previous section there are two major variations in the response format.
When the callback and context arguments are not supplied, the
response format is a simple JSON object similar to the snippets shown below:
{
"responseData" : {
"translatedText" : the-translated-text,
"detectedSourceLanguage"? : the-source-language
},
"responseDetails" : null | string-on-error,
"responseStatus" : 200 | error-code
}
{
"responseData" : {
"language" : the-detected-language,
"isReliable" : the-reliability-of-the-detect,
"confidence" : the-confidence-level-of-the-detect
},
"responseDetails" : null | string-on-error,
"responseStatus" : 200 | error-code
}
In the JSON fragment above, note that the responseData property contains
method specific properites that are identical to the properties available in the JavaScript binding.
For additional information
please review the Result Objects discussion. Note that in this portion of the document, there is
an optional error object described. When using the URL based protocol, the error
property is never present. Instead, the responseStatus and responseDetails properties are used.
The responseStatus property contains a value of 200 on success and a non-200 http error status code on failure.
If there is a failure, responseDetails contains a diagnostic string.
If the application supplies both callback and context arguments,
the response is encoded as a JavaScript procedure call. In this mode of operation, the
value of callback becomes the procedure call target, the value of
context is passes as the first argument, the value of responseData from
above is passes as the second argument, the response status is passed as the third argument, and the final
argument is either null or a diagnostic string.
foo('bar',{"translatedText":"Ciao mondo","detectedSourceLanguage":"en"},
200, null)
The Translate method supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| langpair |
This argument supplies the optional source language and required destination language. The
language pairs are seperated by a properly escaped | vertical bar which escapes
as %7C. In order to translate from English to Italian, you would specify a value of langpair=en%7Cit.
To use the aut-detect source feature, leave off the source language and only specify the vertical bar followed by the
destination langauge as in: langpair=%7Cit.
|
| format? |
This optional argument allows you to indicate that the text to be translated is
either plain-text or HTML. A value of html indicates html and a value of text indicates
plain-text. Note that text is the default behavior.
|
The Detect Language method has no additional arguments. All arguments are listed above.
The Lookup Feed method has no additional arguments. All arguments are listed above.