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.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.
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).
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.
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.57The following example shows how to display currency in Euros.
dojo.debug(dojo.i18n.currency.format("1234.567", "EUR"));DEBUG: EUR: € 1,234.57
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.
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.
TODO: show examples of declaring/overriding locale; explain that locales will only function if part of the operating set.
TBD
Author: Peller