Developer's Guide
With the AJAX Language API, you can translate and detect the language of blocks of text within a webpage using only Javascript.
The API is new, so there may be bugs and slightly less than perfect documentation. Bear with us as we fill in the holes, and join the AJAX APIs developer forum to give feedback and discuss the API.
Table of Contents
Audience
This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. There are many JavaScript tutorials available on the Web.
Introduction
The "Hello, World" of the Google AJAX Language API
The easiest way to start learning about this API is to see a simple example. The following example will detect the language of the given text and then translate it to English.
<html>
<head>
<script type="text/javascript" src="http://www.google.com/jsapi">script>
<script type="text/javascript">
google.load("language", "1");
function initialize() {
var text = document.getElementById("text").innerHTML;
google.language.detect(text, function(result) {
if (!result.error && result.language) {
google.language.translate(text, result.language, "en",
function(result) {
var translated = document.getElementById("translation");
if (result.translation) {
translated.innerHTML = result.translation;
}
});
}
});
}
google.setOnLoadCallback(initialize);
script>
head>
<body>
<div id="text">你好，很高興見到你。div>
<div id="translation">div>
body>
html>
You can view this example here to edit and play around with it.
Including the AJAX Language API on Your Page
To include the AJAX Language API in your page, you will utilize the Google AJAX API loader. The common loader allows you to load all of the AJAX apis that you need, including the language API. You need to both include the Google AJAX APIs script tag and call google.load("language", "1"):
<script type="text/javascript" src="http://www.google.com/jsapi">script>
<script type="text/javascript">
google.load("language", "1");
script>
The first script tag loads the google.load function, which lets you load individual Google APIs. google.load("language", "1") loads Version 1 of the Language API. Currently the AJAX Language API is in Version 1, but new versions may be available in the future. See the versioning discussion below for more information.
API Updates
The second argument to google.load is the version of the AJAX Language API you are using. Currently the AJAX Language API is in version 1, but new versions may be available in the future.
If we do a significant update to the API in the future, we will change the version number and post a notice on Google Code and the AJAX APIs discussion group. When that happens, we expect to support both versions for at least a month in order to allow you to migrate your code.
The AJAX Language API team periodically updates the API with the most recent bug fixes and performance enhancements. These bug fixes should only improve performance and fix bugs, but we may inadvertently break some API clients. Please use the AJAX APIs discussion group to report such issues.
Examples
Language Translation
This example shows a simple translation of a javascript string.
google.language.translate("Hello world", "en", "es", function(result) {
if (!result.error) {
var container = document.getElementById("translation");
container.innerHTML = result.translation;
}
});
Language Detection
This example shows language detection of a javascript string. The language code is returned
var text = "¿Dónde está el baño?";
google.language.detect(text, function(result) {
if (!result.error) {
var language = 'unknown';
for (l in google.language.Languages) {
if (google.language.Languages[l] == result.language) {
language = l;
break;
}
}
var container = document.getElementById("detection");
container.innerHTML = text + " is: " + language + "";
}
});
Source Detection during Translation
The following example is similar to the basic translation example but shows how to translate the text without knowing the source language. By specifying an empty string as unknown for the source language, the system will detect and translate in one call.
google.language.translate("Hello world", "", "es", function(result) {
if (!result.error) {
var container = document.getElementById("translation");
container.innerHTML = result.translation;
}
});
View example (autotranslate.html)
Some Additional Samples
Here are two addional samples that allow some interaction. The first does language detection with a pre-canned text string but allows other text to be input. It also display confidence and reliability factors.
The second additional sample does translation. However it will also allow interaction similar to the sample above.
API Details
Supported Languages
The Google AJAX Language API currently supports the following languages. The technology is constantly improving and the team is working hard to expand this list, so please check back often. You can also visit Google Translate to view an up to date list.
- Afrikaans New!
- Albanian New!
- Amharic New!
- Arabic
- Armenian New!
- Azerbaijani New!
- Basque New!
- Belarusian New!
- Bengali New!
- Bihari New!
- Bulgarian New!
- Burmese New!
- Catalan New!
- Cherokee New!
- Chinese (Simplified and Traditional)
- Croatian New!
- Czech New!
- Danish New!
- Dhivehi New!
- Dutch
- English
- Esperanto New!
- Estonian New!
- Filipino New!
- Finnish New!
- French
- Galician New!
- Georgian New!
- German
- Greek
- Guarani New!
- Gujarati New!
- Hebrew New!
- Hindi New!
- Hungarian New!
- Icelandic New!
- Indonesian New!
- Inuktitut New!
- Italian
- Japanese
- Kannada New!
- Kazakh New!
- Khmer New!
- Korean
- Kurdish New!
- Kyrgyz New!
- Laothian New!
- Latvian New!
- Lithuanian New!
- Macedonian New!
- Malay New!
- Malayalam New!
- Maltese New!
- Marathi New!
- Mongolian New!
- Nepali New!
- Norwegian New!
- Oriya New!
- Pashto New!
- Persian New!
- Polish New!
- Portuguese
- Punjabi New!
- Romanian New!
- Russian
- Sanskrit New!
- Serbian New!
- Sindhi New!
- Sinhalese New!
- Slovak New!
- Slovenian New!
- Spanish
- Swahili New!
- Swedish New!
- Tajik New!
- Tamil New!
- Tagalog New!
- Telugu New!
- Thai New!
- Tibetan New!
- Turkish New!
- Ukranian New!
- Urdu New!
- Uzbek New!
- Uighur New!
- Vietnamese New!
Supported Language Translation Pairs
The Google AJAX Language API currently detects all languages listed above. A subset of those languages are translatable and are listed below. Any two languages from the following list can be translated. To test if a language is translatable, utilize google.language.isTranslatable(languageCode);
- Arabic
- Bulgarian New!
- Chinese (Simplified and Traditional)
- Croatian New!
- Czech New!
- Danish New!
- Dutch
- English
- Finnish New!
- French
- German
- Greek
- Hindi New!
- Italian
- Japanese
- Korean
- Norwegian New!
- Polish New!
- Portuguese
- Romanian New!
- Russian
- Spanish
- Swedish New!
Flash and other Non-Javascript EnvironmentsNew!
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.
The easiest way to start learning about this interface is to try it out... Using the command line tool curl or wget execute the following command:
curl -e http://www.my-ajax-site.com \
'http://ajax.googleapis.com/ajax/services/language/translate?v=1.0&q=hello%20world&langpair=en%7Cit'
This command performs a Language Translation(/ajax/services/language/translate), for Hello World (q=hello%20world) from English to Italian (langpair=en%7Cit). The response has a Content-Type of text/javascript; charset=utf-8. You can see from the response below that the responseData is identical to the properties described in the Result Objects documentation.
{"responseData": {
"translatedText":"Ciao mondo"
},
"responseDetails": null, "responseStatus": 200}
In addition to this response format, the protocol also supports a classic JSON-P style callback which is triggered by specifying a callback argument. When this argument is present the json object is delivered as an argument to the specified callback.
callbackFunction(
{"responseData": {
"translatedText":"Ciao mondo"
},
"responseDetails": null, "responseStatus": 200})
And finally, the protocol supports a callback and context argument. When these url arguments are specified, the response is encoded as a direct Javascript call with a signature of: callback(context, result, status, details, unused). Note the slight difference in the following command and response.
curl -e http://www.my-ajax-site.com \
'http://ajax.googleapis.com/ajax/services/language/translate?v=1.0&q=hello%20world&langpair=en%7Cit&callback=foo&context=bar'
This command performs a Language Translate and is identical to the previous call, BUT has been altered to pass both callback and context. With these arguments in place, instead of a JSON object being returned, a Javascript call is returned in the response and the JSON object is passed via the result parameter.
foo('bar', {"translatedText":"Ciao mondo"}, 200, null)
Code SnippetsNew!
The AJAX Search API documentation includes a small collection of code snippets that demonstrate access to the service from Flash, Java, and Php. The language specific part of this is uniform across all of the AJAX APIs so instead of repeating the snippets, please view via this link.For complete documentation on this interface, please visit the class reference manual.
Troubleshooting
If you encounter problems with your code:
- Look for typos. Remember that JavaScript is a case-sensitive language.
- Use a JavaScript debugger. In Firefox, you can use the JavaScript console or the FireBug extension. In IE, you can use the Microsoft Script Debugger.
- Search the AJAX APIs discussion group. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.
