Translator

This API is used for language internationalization of the Process Platform Ajax Toolkit Web pages.

Syntax

HTML	<div cordysType="wcp.library.util.Translator" id="listID"> <div/> </div>

The translator component translates the Process Platform Web pages to different languages that are defined in an XML source file called dictionary. The dictionary file is of the type .translation and contains various HTML tags used in the page and the language equivalents that are supported by the Process Platform Ajax Toolkit.

The component loads the dictionary file for that page from the URL given by the dictionary property. The translator, on becoming active uses the language specifications from the default browser settings to convert the tokens in the HTML page to the language specified in the user settings or by the user.

To translate an HTML page, the tokens in the page that needs to be translated must contain a property translatable whose value can be set to true as in the following <LABEL>tag.

HTML	<LABEL translatable=true>This is a text</LABEL>

If the text to be translated is too long, it can be referenced in the dictionary file using a label ID. In such cases, the tokens have an additional property label_id set to the label in the dictionary file. The search is based on the label_id and if it is not found, the default text is considered. The label_id can contain the text to be translated or the label reference for a particular text. The following example shows how a translator can be used to translate text inside a shortcut menu item:

HTML	`<menuitem translatable=true label_id='lbl1'>This is a long text, which uses a label_id for translation</menuitem>`

The translatable strings can also contain HTML nodes inside them and it must be a valid XHTML string. This support is extended for the DIV and SPAN tags. The following example shows a DIV tag that can be translated to any language using the label_id attribute:

HTML	`<DIV translatable=true label_id="label2"><font color= 'red'><b>Stop</b></font></DIV>`

Following are the tags and the attributes that are considered by the translator component for translation:

Tags	Attributes
BUTTON	Translatable attribute is innerHTML
INPUT	Translatable attribute is value. In addition, if type=image, then the image (src attribute) can also be changed according to different languages
IMAGE	Translatable attribute is src
HTML Heading tags (H1, H2, H3, H4, H5 and H6)	Translatable attribute is innerText
LABEL	Translatable attribute is innerText
OPTION	Translatable attribute is innerText
menuitem	Translatable attribute is innerText
DIV and SPAN	Translatable attribute is innerHTML
common	Attributes such as `title`, `alt` that are common to all the HTML elements. The `tooltip` and `msg` validate component attributes are also translatable.

In addition, the translator is extended to register any dynamic tag that is created by the HTML components. With this feature, a developer can register any HTML tag or attributes that are not specified above. These elements are considered by the translator for translation at the runtime by calling the registerTag() method.

To dynamically add and initialize this component, you can use the initializeHTMLElements or addType methods of the application object.

The various properties, methods, and events that are defined for the translator component are as follows:

Table 1. List of Attributes

Attribute	Property	Description
active	active	String that denotes whether the translator component is loaded and available for use. This is a `Read-only` property and does not have default values. The onactive event is fired by the component when this state is reached. true: The dictionary file is loaded for that page from the dictionary URL and the translator is completely loaded. false: The translator is not completely loaded.
applicationLanguage	applicationLanguage	String that denotes the language in which the application is running. When translator is loaded for the first time, this property ensures that the translator is not run when the languages are the same. This property takes the same values as the `newLanguage` property.
dictionary	dictionary	String that denotes the URL of the dictionary XML file (defined as the page dictionary).
id	id	String that denotes the unique identifier of the translator component. By default, this is translator.
ontranslate	ontranslate	Pointer to a function that will be executed each time before an element is being translated.
newLanguage	N/A	Sets the `newLanguage` property, which is a string that denotes the current language of the page. The property value must be set to the ISO code of the corresponding language to which it is changed. The translator, on becoming active uses the language specifications from the default browser settings to convert the tokens in the HTML page to the language specified in the user settings or by the user. When the language is changed by the translator component, all the HTML elements in the page are translated and the onlanguagechange event is fired.

Table 2. List of Methods

Method	Description
appendDictionary(surl)	Appends a dictionary to an application. The `surl` denotes the URL of the dictionary to be added. The translator component appends the dictionary to the end of the available labels. Therefore, the definition that exists already is not overridden. A search for a specific translatable item will always return the item from the first dictionary and if unavailable, it goes for the second one.
setMessageBundle(bundle)	Sets the Message Bundle for the translator.The bundle can be a Javascript Message Bundle Path or <Messagebundle> Object.
translateXML(xmlNode)	Translates XML.The XML node specified with the translatable=true attribute is replaced with the translation in the current language. Alternatively, the text identifiers can be specified using the `label_id`.
translateElement(element)	Translates an HTML element.The HTML element specified with the translatable= true attribute is replaced with the translation in the current language.
registerHTML	Registers the element specified to the translator component
registerTag	Registers any HTML tag or attribute that are is considered by the translator for translation
getNewLanguage	Retrieves the value of the `newLanguage` property
setNewLanguage	Sets the `newLanguage` property, which is a string that denotes the current language of the page. The property value must be set to the ISO code of the corresponding language to which it is changed. The translator, on becoming active uses the language specifications from the default browser settings to convert the tokens in the HTML page to the language specified in the user settings or by the user. When the language is changed by the translator component, all the HTML elements in the page are translated and the onlanguagechang e event is fired.
getCordysTranslatedText(text) Deprecated	Takes the text to be translated as an input, translates it to the current language the user is in, and returns the translated text. Use this API instead of the `translate(text)` API. Use localization_get() for XForms and localization.get() for web pages.
translate(text) Deprecated. Use `getCordysTranslatedText(text) for existing applications`.	Takes text to be translated as an input, translates it to the current language in which the user is in, and returns the translated text.

Table 3. List of Events

Event	Description
onactive	Fires when the translator component is fully loaded and ready to use
onlanguagechange	Fires whenever there is a language change, which is when the `newLanguage` property is set.

Remarks

Process Platform Ajax Toolkit also comes with translator support enabled for the Explorer page in the Process Platform Site. The default dictionary URL for the daemon page of the Process Platform Site is given by the URL /cordys/wcp/admin/explorer.translation; this does not contain any data in it. The user can translate the Process Platform daemon page (Left tree) by appending the dictionary to the daemon page, which is as follows:

system.windows["Menu"].translator.appendDictionary(surl);

where surl denotes the URL of the translator document.

Note:

A dictionary file is stored with an extension .translation.
To register items that are added dynamically (shortcut menus, tree items and so on), the registerHTML() method must be called. For example, while adding a dynamic shortcut menu, retrieve the element returned by the addItem() method of the contextmenu and call the registerHTML() method.
The label_id property does not support the translation of the tooltip and toolbar captions. To translate a tooltip or a toolbar caption or description, the text inside the tooltip or the toolbar caption or description itself is used. Tooltips can be defined using the title property of HTML elements, the alt property of IMG tags, or the tooltip attribute of the validate component.
To translate an element, which has an attribute that is common to all HTML elements, the registerTag() method of the translator component can be called with the tagName parameter as "" or null . Examples for such attributes are alt, tooltip, and so on.

Example

A demo page for the translator library demonstrates the use of this component. In this demo, a dictionary is attached to the page, which is used by the translator component to translate the Menu Item, tree, DIV tags, and so on defined in the page.