dojo/i18n¶
| Project owner: | Adam Peller |
|---|---|
| since: | V1.0 |
Contents
dojo/i18n is a module the provides internationalization (i18n) features for Dojo. It also operates as a plugin for loading text resources based on a locale.
Introduction¶
dojo/i18n solves a problem in JavaScript: with a significant amount of logic now on the client, there are
internationalization issues which cannot easily be solved by server-driven templates. Furthermore, a server-based
solution for dynamic content is difficult to manage and couples the client-side toolkit to a particular server
architecture, making it difficult to share JavaScript components or widgets. With a client-side internationalization
framework, the integration point moves to the browser where simple or complex logic can be applied without becoming a
bottleneck. This architecture also encourages encapsulation and efficient caching both at edge servers and in the
browser. And, while all translations are present on the server, rest assured that only those which match the user’s
locale are requested by the client and sent over the wire.
To internationalize a web application with Dojo, a combination of client and server techniques are typically employed. The methods used in Dojo to substitute localized resources are intended for dynamic content generated by JavaScript. It is usually best to continue using a server-side mechanism to localize static page content, rather than trying to generate all page content through Dojo and JavaScript.
Dojo and Dijit provide resource bundles for all strings which are made visible to the user on the page, with translations provided in many languages. Those augmenting Dojo or writing their own widgets may to create and translate their own set of resources, as needed. Error information, such as that sent to a browser console, are not translated.
Usage¶
The main usage is to use the plugin to load a “bundle” of resources. The plugin will detect the current user locale of the web browser, coupled with the available translations by language and return the most appropriate bundle:
require(["dojo/i18n!myApp/nls/myResources"], function(myResources){
// myResources will contain the appropriate strings
});
The localized content is simply an Object with properties. Where the root file (in the case above would be
myApp/nls/myResources.js) contains the default translations plus any other information about supported locales.
For example:
define({
root: {
greeting: "Hello, world!"
}
de: true,
"de-at" : true
});
This would provide a default greeting string, unless your local was de (German) or one of its variants, unless
your locale is de-at (Austrian German) where you will get a variant translation.
We would need to provide two additional files, one at myApp/nls/de/myResources.js:
define({
greeting: "Hallo, Welt!"
});
And then at myApp/nls/de-at/myResources.js:
define({
greeting: "Grüß Gott!"
});
When you are using the dojo/i18n against “un-built” code, the way the plugin attempts to resolve the “best” locale
for the user is to potentially make multiple server side requests. This can be high inefficient in a production
application so the builder will flatten the NLS bundles into single files to make it more
efficient. You can also specify which locales you want built into your production application.
Examples¶
This example retrieves some of the strings that are bundled with Dijit. What should appear is the translations in whatever your browser’s local locale is.
require(["dojo/i18n!../../_static/dijit/nls/common.js", "dojo/dom-construct", "dojo/domReady!"],
function(common, domConst){
domConst.place("<ul>"
+ "<li> buttonOk: " + common.buttonOk + "</li>"
+ "<li> buttonCancel: " + common.buttonCancel + "</li>"
+ "<li> buttonSave: " + common.buttonSave + "</li>"
+ "<li> itemClose: " + common.itemClose + "</li></ul>",
"output"
);
});
<h2>Translations Loaded</h2>
<div id="output"></div>