# Transliterate API Reference ## Simple transliteration The following method allows you to perform simple transliteration without a UI by manipulating JavaScript. | Method | Description | |---|---| | `google.language.transliterate(wordsArray, srcLang, destLang, callback)` | `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/reference#LanguageCode) for examples. - `destLang` provides the destination language as a language code. See the [`LanguageCode` enum](https://developers.google.com/transliterate/v1/reference#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`. | ## Transliteration control JavaScript reference The following constructor and methods allow you to perform transliteration within a UI provided by the API. ### Constructor - `google.elements.transliteration.TransliterationControl(options)` | Constructor | Description | |---|---| | `google.elements.transliteration. TransliterationControl(options)` | `.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/reference#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/reference#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/reference#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); } ``` | ### Transliteration control methods The following methods are implemented on the `google.elements.transliteration.TransliterationControl` namespace. | Method | Description | |---|---| | `.addEventListener(eventType, listener, opt_listenerScope)` | `.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/reference#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/reference#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. | | `.disableTransliteration()` | `.disableTransliteration()` disables transliteration in the transliteration control. This method has no arguments and no return value. | | `.enableTransliteration()` | `.enableTransliteration()` enables transliteration in the transliteration control. This method has no arguments and no return value. | | `.isTransliterationEnabled()` | `.isTransliterationEnabled()` has no arguments and returns a boolean indicating whether transliteration is enabled in the transliteration control. | | `.makeTransliteratable(elementIds, opt_options)` | `.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. | | `.removeEventListener(eventType, listener, opt_listenerScope)` | `.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/reference#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. | | `.setLanguagePair(sourceLanguage, destinationLanguage)` | `.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/reference#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. | | `.showControl(divElement)` | `.showControl(divElement)` shows the transliteration control in the specified DIV, where `divElement` is the id of the DIV. This method has no return value. | | `.toggleTransliteration()` | `.toggleTransliteration()` turns transliteration on or off in the transliteration control. This method has no arguments and no return value. | ### Static method The following static method is implemented on the `google.language` namespace. | Static method | Description | |---|---| | `.setOnLoadCallback(callback)` | `.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. | The following static method is implemented on the `google.elements.transliteration` namespace. | Static method | Description | |---|---| | `.getDestinationLanguages(sourceLanguage)` | `.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/reference#LanguageCode). | ## 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] }; ``` ## 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.