This developer's guide demonstrates how to use the Google Transliterate API. With this JavaScript API, you can detect the language of a given text block and transliterate it into a different script.
## Introduction
This developer's guide provides a basic model for using the Google Transliterate API, along with granular explanations of the API's configurable JavaScript components. You can use this guide to transliterate text on your page.
### Scope
This document describes how to use the functions and properties specific to the Transliterate API.
### Browser compatibility
The Transliterate API supports Firefox 1.5+, IE6+, Safari, and Chrome. The Transliterate API can be loaded without errors in almost every browser, so you can safely load it before checking for compatibility.
Different applications sometimes require different behaviors for users with incompatible browsers. The Transliterate API provides a global method [`google.elements.transliteration.isBrowserCompatible()`](https://developers.google.com/transliterate/v1/getting_started#isBrowserCompatible) to check compatibility, but it does not have any automatic behavior when it detects an incompatible browser. For usability purposes, you should detect incompatible browsers and, if detected, display an error message.
### Audience
This documentation is intended for developers who wish to add Google Transliterate functionality to their pages or applications.
### HTML Content Type
The Transliterate API handles a lot of UTF-8 text and you therefore need to set the `content-type` of your page to UTF-8 by adding this meta tag ``. Without this meta tag, the Transliterate API will not work properly.
### The "Hello World" of Google Transliterate
```
Type in Hindi (Press Ctrl+g to toggle between English and Hindi)
```
## Getting started
### Load the JavaScript API
To begin using the Transliterate API, include the following script in the header of your web page.
```
```
Next, load the Transliterate API with `google.load(module, version, package)`, where:
- `module` calls the specific API module you wish to use on your page (in this case, `elements`).
- `version` is the version number of the module you wish to load (in this case, `1`).
- `package` specifies the specific elements package you wish to load, in this case `transliteration`.
```
```
You can find out more about google.load in the [Google Loader developer's guide](https://developers.google.com/loader).
When we do a significant update to the API, we will increase the version number and post a notice on the [API discussion group](http://groups-beta.google.com/group/Google-AJAX-Search-API). Take note of any required code changes when this occurs, and update your URLs to the new version when they are compliant.
The Google API team will also periodically update the API with recent bug fixes and performance enhancements without requiring a version update. For the most part, these fixes should remain transparent to you, but we may inadvertently break some API clients. Please use the [API discussion group](http://groups-beta.google.com/group/Google-AJAX-Search-API) to report such issues.
## Using the API
The following sections demonstrate how to incorporate the Google Transliterate API into your web page or application. Using this API requires an asynchronous call to a server, so you need a callback function to process the data exchange.
### Performing simple transliteration
`google.language.transliterate(wordsArray, srcLang, destLang, callback)` is a global method that transliterates given text from the source language to the destination language. The API returns the result asynchronously to the given `callback` function as the `result` object. Parameters for this method are:
- `wordsArray` provides the text to be transliterated as an array.
- `srcLang` provides the source language as a language code. See the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode) for examples.
- `destLang` provides the destination language as a language code. See the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode) for examples.
- `callback` is the callback function that receives the `result`.
`google.language.transliterate()` has no return value.
This simplified method for transliteration uses the `google.language.transliterate` namespace (and not `google.elements.transliteration`, which is the namespace for every other method in the Transliterate API).
`google.language.transliterate()` outputs the `result` object.
Result objects are produced using a JSON encoding of server requests. Consequently, we have chosen not to implement formal JavaScript objects, and instead dynamically created the `result` objects from their serialized form.
While there is no formal implementation of the objects, they exist, and we document them as if there was a backing JavaScript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, it's as if the system called new Object() and then set formal properties on that object. These properties are below.
- \
- `error?` Present if there was an error in transliteration.
- `code` An [HTTP-style error code.](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
- `message` A human-readable string description of the error.
- `transliterations` An array of size equal to the size of the input `wordsArray`.
- `transliteratedWords` An array of maximum size 5, with transliterations for the corresponding word in `wordsArray`.
This example shows how to transliterate a JavaScript string:
```
//Load the Language API.
google.load("language", "1");
//Call google.language.transliterate()
google.language.transliterate(["Namaste"], "en", "hi", function(result) {
if (!result.error) {
var container = document.getElementById("transliteration");
if (result.transliterations && result.transliterations.length > 0 &&
result.transliterations[0].transliteratedWords.length > 0) {
container.innerHTML = result.transliterations[0].transliteratedWords[0];
}
}
});
```
[View example (transliterate.html)](https://developers.google.com/transliterate/v1/transliterate)
### Enabling the transliteration control
`.TransliterationControl(options)` enables transliteration on a set of editable HTML DOM elements and supplies a number of methods allowing you to control transliteration in those elements. The `options` argument can have the following fields:
- `sourceLanguage` is a **mandatory** string that specifies the source language using the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode) (as in `google.elements.transliteration.*ENGLISH*`). Currently, English is the only supported source language.
- `destinationLanguage` is a **mandatory** array that specifies the destination language using the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode) as in (as in `google.elements.transliteration.*HINDI*` ).
In the UI, the available destination languages appear in the menu, with the first language in the array selected by default. Please refer to [getDestinationLanguages](https://developers.google.com/transliterate/v1/getting_started#getDestinationLanguages) for more details regarding valid destination languages for a given source language.
- `transliterationEnabled` is an optional field specifying whether to enable transliteration by default. If you wish to enable transliteration by default, specify this field with a value of `true`. The default value is `false`.
- `shortcutKey` is an optional string field that specifies a shortcut key to toggle transliteration on or off. To specify the shortcut key, specify a string containing modifiers such as 'Ctrl', 'Alt' or 'Shift' along with an alphabetic letter. For example, 'Ctrl+g' and 'Ctrl+Shift+a' are both valid shortcut key combinations.
**Note:** You cannot use Shift as the only modifier; however, you can use it in combination with Alt or Control.
This method creates exceptions in the following circumstances:
- Invalid `sourceLanguage` or `destinationLanguage`
- Unsupported languages in the `sourceLangauge` and `destinationLanguage` language pair
- Invalid shortcutKey combination
The following code snippet demonstrates how to create an instance of the transliteration control:
```
function onLoad() {
var options = {
sourceLanguage: 'en',
destinationLanguage: ['hi'],
shortcutKey: 'ctrl+g',
transliterationEnabled: true
};
// Create an instance on TransliterationControl with the required
// options.
var control = new google.elements.transliteration.TransliterationControl(options);
}
```
#### Enabling transliteration in an HTML node
`.makeTransliteratable(elementIds, opt_options)` enables transliteration on the supplied HTML element(s). Parameters for this method are:
- `elementIds` is an array containing strings of editable element IDs or element references for which you wish to enable transliteration. An editable element can be:
- A text field
- A text area
- A \ with `contentEditable="true"`
- An \ with `designMode="on"`
- An iFrame with `contentEditable="true"` body. Make sure the iFrame is loaded before enabling transliteration.
- `opt_options` is an optional argument that supplies the options applied to these elements. This argument can contain the following fields:
- `adjustElementStyle` is an optional boolean field controlling whether the API automatically adjusts the element and font sizes to optimally suit target language characters. The default value is `true`. This option affects only the plain text elements.
- `adjustElementDirection` is an optional boolean field controlling the direction of the editable element depending on the direction of the `destinationLanguage`. The default value is `true`.
For right-to-left writing systems like Arabic, the API automatically adjusts the direction of the input element, according to the direction of the written script and the content of the input element. You can set the direction of text in an input element using HTML and JavaScript with `direction`, which can have the value `'ltr'` (left to right) or `'rtl'` (right to left). Using this method affects the cursor and alignment of text in the input area.
You can see an example of the API's support for right-to-left languages in the [Arabic transliteration example](http://code.google.com/apis/ajax/playground/#transliterate_arabic).
This method creates exceptions if any of the specified `elementIds` is invalid.
`.makeTransliteratable()` has no return value.
The following code snippet demonstrates a typical use of this method:
```
var ids = [ "transl1", "transl2" ];
control.makeTransliteratable(ids);
```
#### Showing the transliteration control in a DIV
`.showControl(divElement)` shows the transliteration control in the specified DIV, where `divElement` is the id of the DIV. This method has no return value.
The following code snippet demonstrates a typical use of this method:
```
control.showControl('translControl');
...
```
#### Turning on transliteration
`.enableTransliteration()` enables transliteration in the transliteration control. This method has no arguments and no return value.
#### Turning off transliteration
`.disableTransliteration()` disables transliteration in the transliteration control. This method has no arguments and no return value.
#### Toggling transliteration on or off
`.toggleTransliteration()` turns transliteration on or off in the transliteration control. This method has no arguments and no return value.
The following code snippet demonstrates a typical use of this method:
```
function checkboxClickHandler() {
transliterationControl.toggleTransliteration();
...
```
#### Changing the language pair for transliteration
`.setLanguagePair(sourceLanguage, destinationLanguage)` allows you to dynamically change the language pair used by the transliteration control, where:
- `sourceLanguage` provides the language type to be transliterated. This argument takes its value from the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode) (such as `google.elements.transliteration.TransliterationControl. LanguageCode.ENGLISH)`.
- destinationLanguage provides the language type for the transliterated text.
`.setLanguagePair()` returns a boolean indicating whether the `setLanguage` action was successful.
The following code snippet demonstrates the use of this method within a handler to change transliteration languages via drop-down menus:
```
function languageChangeHandler() {
var dropdown = document.getElementById('languageDropDown');
transliterationControl.setLanguagePair(
google.elements.transliteration.LanguageCode.ENGLISH,
dropdown.options[dropdown.selectedIndex].value);
}
...
```
#### Retrieving the current language pair
`.getLanguagePair()` has no arguments and returns the current language pair for the transliteration control as an object with fields for `sourceLanguage` and `destinationLanguage`.
#### Detecting if transliteration is enabled
`.isTransliterationEnabled()` has no arguments and returns a boolean indicating whether transliteration is enabled in the transliteration control.
The following code snippet uses this method to check a checkbox if transliteration is enabled:
```
// Set the checkbox to the correct state.
document.getElementById('checkboxId').checked =
transliterationControl.isTransliterationEnabled();
...
```
#### Adding a listener for transliteration events
`.addEventListener(eventType, listener, opt_listenerScope)` adds a listener to the transliteration control for the specified event type. When the particular event type is triggered, the listener is called with the event object. The contents of the event object depend on the [type of the event](https://developers.google.com/transliterate/v1/getting_started#EventType). Parameters for this method are:
- `eventType` is the event for which the listener is to be added. This argument takes its value from the [`eventType` enum](https://developers.google.com/transliterate/v1/getting_started#EventType) (such as `google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED)`.
- `listener` provides a listener function for the event.
- `opt_listenerScope` calls the listener with `this` set to the object specified in `opt_listenerScope`.
`.addEventListener()` has no return value.
The following code snippet demonstrates how to use this method to display an error message if the server is unreachable:
```
transliterationControl.addEventListener(
google.elements.transliteration.TransliterationControl.EventType.SERVER_UNREACHABLE,
serverUnreachableHandler);
function serverUnreachableHandler(e) {
document.getElementById("errorDiv").innerHTML =
"Transliteration Server unreachable";
}
...
```
#### Removing a listener for transliteration events
`.removeEventListener(eventType, listener, opt_listenerScope)` removes an event listener from the transliteration control, where:
- This argument takes its value from the [`eventType`](https://developers.google.com/transliterate/v1/getting_started#EventType) enum (such as `google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED)`.
- `listener` is the function for the event that needs to be removed.
- `opt_listenerScope` is the scope in which the listener was registered at the time of adding the listener.
`.removeEventListener()` has no return value.
The following code snippet demonstrates how to remove the event listener created in the previous example:
```
transliterationControl.removeEventListener(
google.elements.transliteration.TransliterationControl.EventType.SERVER_UNREACHABLE, serverUnreachableHandler);
```
### Customizing the visible components
You can style the transliteration control that is displayed using the `showControl` method to extend the classes defined in the default CSS file. The API loads this CSS file automatically via `google.load()`. This CSS file defines the styles for the control and the transliteration suggestions menu that pops out when you click or edit a transliterated word. If you do not want to load the default CSS, set `nocss` to `true` when you call `google.load`.
```
google.load("elements", "1", {packages: "transliteration", "nocss" : true});
```
The language selection menu, the button indicating the language selected by the user and the suggestion menu are enclosed in DIV elements marked with specific CSS classes. You can define overriding CSS rules that are applied to these elements in order to style them according to your page. Please refer to [this documented transliteration CSS file](https://developers.google.com/static/transliterate/v1/transliteration.css) for details of the default CSS loaded with the Transliterate API package.
### Calling the onLoad handler
`.setOnLoadCallback(callback)` is a static function that registers the specified handler function to be called once the page containing this call loads, where `callback` is a required function called when the containing document is loaded and the API is ready for use (e.g., after `onLoad`). This function is implemented on the `google` namespace (i.e., `google.setOnLoadCallback(callback);`)
`.setOnLoadCallback()` has no return value.
**Note:** Previous documentation recommended that you use the body element's onload attribute (``). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your `body.onload` handler. `setOnLoadCallback()` does not have these problems, and therefore is the recommended method of registering a callback that calls your code when the API is fully loaded and ready for use.
`setOnLoadCallback` is implemented on the `google` namespace:
```
google.setOnLoadCallback(function);
```
### Configuring additional methods
In addition to the methods listed above, the Transliterate API also offers the following, global methods allowing you to improve the usability of your applications. These methods are built on the `google.elements.transliterate` namespace.
#### Detecting if the current browser supports transliteration
`.isBrowserCompatible` is a global method with no arguments that returns a boolean indicating whether transliteration is available for the client's browser.
The following code snippet demonstrates how to detect browser support for transliteration:
```
...
if (google.elements.transliteration.isBrowserCompatible()) {
var transliterationControl = new google.elements.transliteration.TransliterationControl(
'sourceLanguage': 'en',
'destinationLanguage': ['hi']);
transliterationControl.makeTransliteratable(['textarea']);
} else {
document.getElementById('errorDiv').innerHTML = 'Sorry! Your browser does not support transliteration';
}
```
#### Finding supported transliteration languages
`.getDestinationLanguages(sourceLanguage)` is a global method that returns a map of destination languages for which transliteration is supported for the given `sourceLanguage`. The returned map contains supported destination languages, in which the key is the language name and the value is the language code. The returned map is similar to the one described in the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/getting_started#LanguageCode).
The following code snippet demonstrates the use of this method:
```
var supportedDestinationLanguages =
google.elements.transliteration.getDestinationLanguages(google.elements.transliteration.LanguageCode.ENGLISH);
```
## Enums
### EventType enum
The `google.elements.transliteration.TransliterationControl.EventType` enumeration lists the events that are possible during transliteration. You can provide custom handlers for these events in your code.
```
var google.elements.transliteration.TransliterationControl.EventType = {
STATE_CHANGED : 'state_changed',
LANGUAGE_CHANGED : 'language_changed',
SERVER_REACHABLE : 'server_reachable',
SERVER_UNREACHABLE : 'server_unreachable'
};
```
- `google.elements.transliteration.TransliterationControl.EventType.STATE_CHANGED`: Results when transliteration is enabled or disabled in the transliteration control via:
- A shortcut key
- The `enableTransliteration`, `disableTransliteration`, or `toggleTransliteration` methods
- A mouse click on the transliteration control drawn by the `showControl` method.
The event object passed to the listener contains the field `transliterationEnabled`. This field is true if transliteration is '`on`', else it is false.
- `google.elements.transliteration.TransliterationControl.EventType.LANGUAGE_CHANGED`: Results when the transliteration language pair is changed in the transliteration control via:
- The `setLanguagePair` method
- The transliteration control drawn by the `showControl` method
The event object passed to the listener contains the fields `sourceLanguage` and `destinationLanguage`.
- `google.elements.transliteration.TransliterationControl.EventType.SERVER_REACHABLE`: Results when you successfully contact the server to transliterate text.
- `google.elements.transliteration.TransliterationControl.EventType.SERVER_UNREACHABLE` results upon a failed attempt to contact the server to transliterate text.
### LanguageCode enum
The `google.elements.transliteration.LanguageCode` maps name constants to language codes that you can use to specify the source and destination languages in the transliteration methods.
```
var google.elements.transliteration.LanguageCode = {
ENGLISH: 'en',
AMHARIC: 'am',
ARABIC: 'ar',
BENGALI: 'bn',
CHINESE: 'zh',
GREEK: 'el',
GUJARATI: 'gu',
HINDI: 'hi',
KANNADA: 'kn',
MALAYALAM: 'ml',
MARATHI: 'mr',
NEPALI: 'ne',
ORIYA: 'or',
PERSIAN: 'fa',
PUNJABI: 'pa',
RUSSIAN: 'ru',
SANSKRIT: 'sa',
SINHALESE: 'si',
SERBIAN: 'sr',
TAMIL: 'ta',
TELUGU: 'te',
TIGRINYA: 'ti',
URDU: 'ur'
};
```
### SupportedDestinationLanguages enum
The `google.elements.transliteration.SupportedDestinationLanguages` enumeration maps name constants to arrays of language codes that you can use to specify groups of destination languages in the transliteration control.
```
var google.elements.transliteration.SupportedDestinationLanguages = {
// ALL includes all languages supported in the Transliterate API.
// As support for more languages becomes available, this enum will be
// automatically updated to include the new languages transparently.
ALL: [
google.elements.transliteration.LanguageCode.AMHARIC,
google.elements.transliteration.LanguageCode.ARABIC,
google.elements.transliteration.LanguageCode.BENGALI,
google.elements.transliteration.LanguageCode.CHINESE,
google.elements.transliteration.LanguageCode.GREEK,
google.elements.transliteration.LanguageCode.GUJARATI,
google.elements.transliteration.LanguageCode.HINDI,
google.elements.transliteration.LanguageCode.KANNADA,
google.elements.transliteration.LanguageCode.MALAYALAM,
google.elements.transliteration.LanguageCode.MARATHI,
google.elements.transliteration.LanguageCode.NEPALI,
google.elements.transliteration.LanguageCode.ORIYA,
google.elements.transliteration.LanguageCode.PERSIAN,
google.elements.transliteration.LanguageCode.PUNJABI,
google.elements.transliteration.LanguageCode.RUSSIAN,
google.elements.transliteration.LanguageCode.SANSKRIT,
google.elements.transliteration.LanguageCode.SERBIAN,
google.elements.transliteration.LanguageCode.SINHALESE,
google.elements.transliteration.LanguageCode.TAMIL,
google.elements.transliteration.LanguageCode.TELUGU,
google.elements.transliteration.LanguageCode.TIGRINYA,
google.elements.transliteration.LanguageCode.URDU],
// INDIC includes all Indic languages supported in the Transliterate API.
// As support for more Indic languages becomes available, this enum will be
// automatically updated to include the new languages transparently.
INDIC: [
google.elements.transliteration.LanguageCode.BENGALI,
google.elements.transliteration.LanguageCode.GUJARATI,
google.elements.transliteration.LanguageCode.HINDI,
google.elements.transliteration.LanguageCode.KANNADA,
google.elements.transliteration.LanguageCode.MALAYALAM,
google.elements.transliteration.LanguageCode.MARATHI,
google.elements.transliteration.LanguageCode.NEPALI,
google.elements.transliteration.LanguageCode.ORIYA,
google.elements.transliteration.LanguageCode.PUNJABI,
google.elements.transliteration.LanguageCode.SANSKRIT,
google.elements.transliteration.LanguageCode.SINHALESE,
google.elements.transliteration.LanguageCode.TAMIL,
google.elements.transliteration.LanguageCode.TELUGU,
google.elements.transliteration.LanguageCode.URDU]
};
```
## Examples
### Transliteration in rich text editors
You can use Transliterate for editors that support rich text editing, such as an editable `div` or `iframe`, or an editable field created using the [Closure library](http://closure-library.googlecode.com/svn/docs/class_goog_editor_Field.html) or [Yahoo! UI Library](http://developer.yahoo.com/yui/editor/). The following sample demonstrates this use case.
```
Transliteration in Rich Text Editor
Type in Hindi (Press Ctrl+g to toggle between English and Hindi)
```
[View example (richedittransliteration.html)](https://developers.google.com/transliterate/v1/richedittransliteration)
### Transliteration control with single language
This example displays a control for switching between English and Hindi typing modes. It also enables transliteration in two text fields.
```
Type in Hindi (Press Ctrl+g to toggle between English and Hindi)
Title :
Body
```
[View example (singlelangtransliteration.html)](https://developers.google.com/transliterate/v1/singlelangtransliteration)
### Transliterate control with multiple languages
This example displays a control allowing the user to choose the destination
language, using the
destinationLanguage option to specify the initial value of the destination language and also list the languages to be supported on the page. For example, if you were interested in having the default destination language on your page be Telugu and also in having Tamil and Malayalam as options in the language dropdown menu, you could specify `destinationLanguage` as `['te',
'ta', 'ml']`.
```
Type in Indian languages (Press Ctrl+g to toggle between English and Hindi)
Title :
Body
```
[View example (multilangtransliteration.html)](https://developers.google.com/transliterate/v1/multilangtransliteration)
### Transliteration with custom control
This is an advanced example which shows how to create your own custom transliteration
control. It uses a checkbox for toggling between English and Hindi typing modes
and a dropdown to change the destination language. It also registers event
handlers for various events that can be raised by the transliteration control.
See the [API class reference](https://developers.google.com/transliterate/v1/reference) for
details on the possible events.
```
Type in Indian languages (Press Ctrl+g to toggle between English and Hindi)
Type in
Title :
Body
```
[View example (customtransliteration.html)](https://developers.google.com/transliterate/v1/customtransliteration)
## Troubleshooting
If you encounter problems:
- Look for typos. Remember that JavaScript is a case-sensitive language.
- Use a JavaScript debugger. Google Chrome has a full set of [developer tools](http://blog.chromium.org/2009/06/developer-tools-for-google-chrome.html). In Firefox, you can use the JavaScript console or the [Firebug](http://www.getfirebug.com/). In IE, you can use the [Microsoft Script Debugger](http://msdn2.microsoft.com/en-us/library/ms532989.aspx).
- Search the [discussion group](http://groups-beta.google.com/group/Google-AJAX-Search-API). 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.