Internationalization and localization in delite

Locale

Delite supports a locale setting for the page. This affects the language of boilerplate text in widgets as well as localizations such as how numbers and dates are displayed. The setting is based on the browser's locale, and affects all widgets on the page.

Note that the HTML lang attribute set on individual elements is ignored. This is because widgets load messages via the i18n! plugin, which uses the locale of the page.

RTL and BIDI support

Delite and dependent projects like deliteful can render widgets in either LTR or RTL. Support for RTL encompasses features like:

GUI layout (ex: whether a Combobox's arrow is to the left or right of the <input> area)
Keyboard control: make sure that the left and right arrow keys move to the left and right (respectively) even when the page is in RTL mode.
textdir property used to control widget text direction independently of GUI direction. See below for details.

has("bidi") flag

If an application will (or may be) run in RTL locales, it should define the has("bidi") flag as follows:

requirejs.config({
    ...
    config: {
        ...
        "requirejs-dplugins/has": {
            bidi: true
        }
    }
});

The has("bidi") flag enables advanced bidi features such as the textdir property. In addition, for some widgets, has("bidi") is necessary to turn on basic RTL features such as correct keyboard handling and proper GUI layout.

has("inherited-dir") flag

If an application will (or may be) run in RTL locales, it in addition can define the has("inherited-dir") flag as follows:

requirejs.config({
    ...
    config: {
        ...
        "requirejs-dplugins/has": {
            bidi: true,
            inherited-dir: true
        }
    }
});

The has("inherited-dir") flag allows a widget to inherit the initial direction from any ancestor node, rather than just <html> or <body>.

Textdir property

The textdir property is useful in two cases:

When the application boilerplate text is LTR, but the user data contained by the application is RTL (or vice-versa). The typical case is that the application boilerplate text is in English, because it hasn't been translated, but the user data displayed by the application is in an RTL language like Hebrew or Arabic.
When the user data (that widgets display) is bidirectional text, for example a sentence in Hebrew that contains words in English.

In either case, textdir declares the "natural text direction", i.e. whether the text should be written right-to-left or left-to-right. For example, in the text "Hello אר!", "Hello" should appear on the left, but in the text "!Bob שלום", the Hebrew word for "hello" appears on the right.

The allowed values are:

"ltr"
"rtl"
"auto" - contextual - the direction of a text defined by first strong letter (see http://en.wikipedia.org/wiki/Bi-directional_text for an explanation of strong characters vs. weak characters)

Note that the textdir property must be set directly on each widget. Unlike dir, textdir will not be inherited from a setting on <html> or <body>.

Limitations of RTL support

For reasons of performance and practicality, delite has certain restrictions on its RTL and bidi support.

Delite's API is currently optimized to support the following cases:

application GUI layout and user data is LTR text
application GUI layout and user data is RTL text

In either case, delite will do the right thing simply by setting <body dir=ltr> or <body dir=rtl>.

Delite also has limited support for displaying part of the page in RTL but other parts in LTR, by directly setting the dir and textdir properties of individual widgets.

In any case, the application should obey the following rules:

Applications should not set dir=ltr or dir=rtl except on <html> or <body>, and on individual widgets, if loader isn't configured with both "bidi" and "inherited-dir" flags.
Applications should not set dir=auto on any widget, nor on any ancestor node.
Applications should not change the dir setting on <html> or <body> after widgets have been instantiated.
If the application changes the dir property of any widget or node, then it must explicitly set dir on all descendant widgets too.

Breaking any of these rules will lead to undefined behavior. Often it will lead to widgets being in a half-way state where, for example, the layout becomes RTL but the keyboard support is still in LTR mode.

Writing widgets

Ibm-js provides two modules that can be used to build widgets with internationalization support:

requirejs-dplugins/i18n - A plugin to load localized text (error messages, etc.) based on the browser's locale.
ecma402 - An implementation of the ECMA-402 JavaScript Internationalization APIs standard for number formatting ( Intl.NumberFormat ) and date and time formatting ( Intl.DateTimeFormat ).

Please see those respective pages for details.