home / dojo / i18n

dojo/i18n

Project owner:Adam Peller
since:V1.0

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>