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 for examples.
  • destLang provides the destination language as a language code. See the LanguageCode enum 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.

  • <result>
    • error?
      Present if there was an error in transliteration.
    • 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 (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 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 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. 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 (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 <div> with contentEditable="true"
    • An <iframe> 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.

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 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 (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 (<body onload="OnLoad()">). 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.

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. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
  • Search the 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.