Internationalization (i18n)

---

Internationalization is the process of making an application available in different locales. A locale is the combination of regional and language data which includes things such as date and time format, text formatting, and providing localized specifc content in a specific encoding. Localization (also referred to as l10n) is the process of making application functionality available in one or more locales. This section will cover the basic concepts of internationalization and show how these features are implemented in Dojo. This section willl cover internationalization and locales, localized Strings, and Date and Time Formatting, Bi-directional text and encoding.

Locales

Localization is driven by a locale, a short string, defined by the host environment, which conforms to RFC 3066 used in the HTML specification. It consists of short identifiers, typically two characters long which are case-insensitive. Note that Dojo uses dash separators, not underscores like Java (e.g. "en-us", not "en_US"). Typically country codes are used in the optional second identifier, and additional variants may be specified. For example, Japanese is "ja"; Japanese in Japan is "ja-jp". Notice that the lower case is intentional -- while Dojo will often convert all locales to lowercase to normalize them, it is the lowercase that must be used when defining your resources.

The locale in the browser is typically set during install and is not easily configurable. Note that this is not the same locale in the preferences dialog which can be used to accompany HTTP requests; there is unfortunately no way to access that locale from the client without a server round-trip.

The dojo.locale property is used to specify the locale of the host environment.



The locale Dojo uses on a page may be overridden by setting djConfig.locale. This may be done to accomodate applications with a known user profile or server pages which do manual assembly and assume a certain locale. You may also set djConfig.extraLocale to load localizations in addition to your own, in case you want to specify a particular translation or have multiple languages appear on your page.

Localizing Strings

dojo.requireLocalization() / dojo.i18n.getLocalization()

The DojoPackageSystem was leveraged to create a mechanism to load locale-specific resources. Resources are associated with Javascript packages and structured as a Javascript object (like JSON notation) with identifiers as indices. The property values may be strings or any other type. Resources may be located within any Javascript package beneath a specially named "nls" directory, with translations made available in directories named by their locale.

dojo.requireLocalization() is used to declare usage of these resources and load them in the same way that dojo.requires() pulls in Javascript packages. An optional locale argument can specify a particular translation to load; otherwise the one best matching the user agent's locale will be used. If djConfig.extraLocale is set, the localizations in that list will be loaded also. A "root" bundle is provided in the case where the requested localization or less-specific variants are not available.

Use dojo.i18n.getLocalization() to get the object (hash) representing the resources. An optional locale may be specified, otherwise the user's environment will specify the locale and the best match loaded by the "requireLocalization" step will be used. The localized values will be available as properties on the returned object. For example:

 dojo.require("dojo.i18n.common");

 dojo.requireLocalization("dojo.widget", "validate", "ja");

var validate = dojo.i18n.getLocalization("dojo.widget", "validate", "ja");

 dojo.debug(validate.invalidMessage);

The example above will display a invalidMessage message from the validate bundle in package dojo.widget.

DEBUG: * 入力��データ�該当�るも���り��ん。



All localized messages and localized content are provided in a "nls" directory (short for native language support) under the specific package. The name of the file containg the localized resources is specified as the second argument. In the example above the default messages would be in a file called src/widget/nls/validate.js, and the Japanese translation would be located at src/widget/nls/ja/validate.js.

Date and Time

Dojo is capable of formatting and parsing date formats for many locales, using a repository based on the work at unicode.org. For example, look at the following date formatted using the default locale (in this case, English/US) and also with a specific locale override of China:

dojo.require("dojo.date.format");
var d = new Date(2006,9,29,4,30);
dojo.date.format(d, {selector:'dateOnly'});
=> "Monday, October 30, 2006"
dojo.date.format(d, {selector:'dateOnly', locale:'zh-cn'})
=> "2006年10月30日星期一"
Other options may be specified to use a different format "length" -- a choice of "short", "medium", "long", or "full" -- or to print only the time portion of the Date object:
dojo.date.format(d, {selector:'dateOnly', formatLength:'short'});
=> "10/30/06"
dojo.date.format(d, {selector:'timeOnly', formatLength:'long', locale:'zh-cn'})
=> "上�04时30分00秒"

Also, it is possible to reverse the process and parse String objects into Dates. Running in a Dutch locale like "nl-nl", the following would produce a valid Date object:

dojo.date.parse("maandag 30 oktober 2006");

Special patterns may be specified, or additional resource bundles may be used to provide sets of localizations for custom formats. The patterns used

follow the specification and are similar to those used by the Java dateformat class (e.g. MMddyyyy).

Numbers

dojo.i18n.number is EXPERIMENTAL. The code is not complete, may not work, and APIs are likely to change.

The formatting of numbers, such as the separator and the handling of decimal places, differs among locales. Dojo will provide the facilities to properly format numbers on a localized basis.

Currency

dojo.i18n.currency is EXPERIMENTAL. The code is not complete, may not work, and APIs are likely to change.

To use these APIs to format a currency in a locale spec manner with the correct number of decimal places and the correct currency symbols. The currency package contains the necessary APIs to format currencies.

dojo.require("dojo.i18n.currency.common");

The following code will be used to format the number 1234.567.

dojo.i18n.currency.format("1234.567", "USD");

dojo.debug(dojo.i18n.currency.format("1234.567", "USD"));



Will result in the following:



DEBUG:  USD: $1,234.57

The following example shows how to display currency in Euros.

dojo.debug(dojo.i18n.currency.format("1234.567", "EUR"));



Will result in:

DEBUG:  EUR: € 1,234.57

Bi-directional Text (BiDi)

Some languages, mostly middle-eastern in origin, have text flow from the right to the left (e.g. Hebrew and Arabic) Again, the web browser generally takes care of this for us, provided the appropriate HTML attributes are set. However, sometimes the logic of an application or widget must change to accomodate bidi. For example, menu widgets drop from the upper-right hand corner of the screen and are right-justified. Some icons may also have different orientation. isLTR() can be checked to provide alternate logic for true and false results.

Dojo provides the dojo.i18n.isLTR() function to specify wether a language is left to right. Most complex widgets, such as Menu are not BiDi enabled yet.

Encoding

The two most important aspects of internationalization are insuring that the inputs and the outputs are in the proper encoding. Thankfully, UTF-8 encoding can be used exclusively on the wire in modern web applications to make this interaction extremely simple. Once read into memory, Javascript treats all strings as a series of double-byte characters and encoding is irrelevant.

Other encodings should be used with great care. A user agent such as one of the current generation browsers infers a page's encoding using the content-type header provided from a server or it may be picked up from a meta tag in the head of a document.

<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />



The most common means of specifying the encoding in a page is to use the meta tag. UTF-8 is the detault encoding used by XML documents exchanged by the XmlHttpRequest object and is encoding that is used internally by Dojo APIs such as dojo.io.bind. We recommend using UTF-8 as the encoding with your internationalized applications.



It is important to properly specify the encoding of the page when forms or form widgets are present as the page's encoding is used to properly encode data that is sent back to a server.

Usage

TODO: show examples of declaring/overriding locale; explain that locales will only function if part of the operating set.

Builds

TBD

Author: Peller