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.
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.
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
nls directory, which stands for "Native Language Support." Figure 1 shows what a typical directory structure would look like.
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
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
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
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
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.
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.