Dojo i18n: A Pure JavaScript Localization Solution

[next]

Some readers of my i18n articles have commented that exploiting a server-side language's localization capability to dynamically retrieve localized strings from the browser creates a lot of overhead. I can't say that I disagree, but just as using Enterprise JavaBeans (EJB) to write a Hello World application is overkill, you wouldn't use Java to display content on a couple of more-or-less static Web pages. That model is well suited to medium- to large-scale Web applications that require a fair degree of localization capability.

As with any architecture that is made of several parts, its value becomes more evident the larger and more complex the application. Here at Canada Border Services, where our applications are released all over the globe and contain thousands of translatable text values, this type of model works very well. For those of you who require something a little more lightweight, I present Dojo's pure JavaScript i18n solution.

Dojo ResourceBundles

Overall, Dojo's i18n module follows the same general structure that I presented in my Using Servlets and JSP to Give Users Control Over Their Presentation Locale article. Content for each locale is stored in resource bundle files, much like Java, on which it's based.

The problem is that JavaScript can't read files that are in the key = value format that Java uses. To get around this limitation, the file contents are formatted as a JavaScript Object Literal, which JavaScript can readily instantiate from a string. Here is an English resource bundle that contains labels for a tax-processing form:

These files can be saved as JavaScript files, using the .js extension, because they are syntactically correct JavaScript code.

Directory Structure

In Dojo, a bundle is a directory named after a locale, which uses the ISO standard identifiers for locales. For example, en-us is the code for English in the U.S. and en-au is English in Australia. Likewise, a Dojo i18n resource is a JavaScript file underneath. As is common in many i18n projects, bundles must be placed in the nls directory, which stands for "Native Language Support." Figure 1 shows what a typical directory structure would look like.

Figure 1: Dojo i18n Directory Structure

Adding Dojo i18n in Your Web Pages

There are a couple of ways to use Dojo in your Web pages. In addition to downloading the files and including them with your other script files, you also have the option of pointing your scripts directly to one of two high-quality content distribution networks provided by Google and AOL. You can utilize the full Dojo Toolkit from one of these services by adding either of the following lines to your HTML page:

To host them yourself, download the full Dojo Toolkit Release from the Dojo download page. Don't just get the Dojo Base because it does not contain the i18n module. If you'd like to be minimalistic, locate the i18n.js file in the dojo folder and copy it to the dojo folder in your Web content directory. You'll also need the string.js file if you want to follow sample code in this article.

Setting the djConfig Variable

The djConfig variable is used to override certain global settings that control how the framework operates, such as enabling debugging and setting the folder structure. You should usually set it before dojo.js is loaded as any changes that you make in djConfig are ignored once the main dojo.js script has been loaded. One way to do that is to add the djConfig attribute to the <script> element that refers to dojo.js:

If you need to set lots of attributes in the djConfig object or prefer not to use Dojo's nonstandard attributes, you can create the djConfig object explicitly before the main dojo.js library included in the document. The code for that would look as follows:

The above code sets the modulePaths and locale variables.

By default, Dojo assumes that the path for any module names that start with a prefix other than "dojo" are in a sibling directory to the dojo directory. For instance, if "scripts/dojo/dojo.js" is the path to dojo.js and you do dojo.require("some.module"), Dojo will try to load the JavaScript file using the path "scripts/some/module.js". If you want to load "some.module" from a different path as we are here, you have to set the modulePath to the containing folder. In the case of the i18n bundles, you should set the modulePath to the parent folder to the nls folder. For us, that's the "gravelleconsulting" root folder, which is two levels up from the "dojo" directory.

The locale sets the default locale if you don't want to depend on the browser's. The default resource bundle is used only when Dojo can't locate a requested bundle, so if you want that one, it's best to specify it here.