Google AJAX Language API

AJAX Language API
- Developer's Guide
- Class Reference

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.

Audience

Introduction: The "Hello, World" of the Google AJAX Language API; Including the AJAX Language API on Your Page; API Updates

Examples: Language Translation; Language Detection; Source Detection during Translation; Branding^New!; Additional Examples

API Details: Supported Languages; Supported Translation Pairs

Flash and other Non-Javascript Environments^New!: Code Snippets

Troubleshooting

Class Reference

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;
  }
});

View example (translate.html)

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 + "";
  }
});

View example (detection.html)

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)

Branding and Google Attribution

When your application uses the Google AJAX Language APIs, it is important to communicate the Google brand to your users. The google.language.getBranding() method is designed to help with this. The method accepts an HTML DOM element or the corresponding id, as well as optional options. The branding is attached to the provided element.

// attach a "powered by Google" branding
<div id='branding'> </div>
...
google.language.getBranding('branding');

The branding can be customized via CSS and comes in a 'vertical' and 'horizontal' base formats. An example showing the various formats and CSS customization is below.

View example (branding.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.

View example (detect.html)

The second additional sample does translation. However it will also allow interaction similar to the sample above.

View example (translate.html)

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!

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 Environments^New!

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 Snippets^New!

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.


e.g. "ajax apis" or "open source"