Localization

The DevExtreme SPA framework provides an easy way to localize your applications. It uses the globalize library and loads translations of specific captions/messages such as 'Back', 'Cancel', 'Select', 'Loading', 'Search' and others to the corresponding languages. The DevExtreme locale extensions are provided by separate dictionary files. These dictionaries can be found in the Lib/js/localization folder within your DevExtreme package. You can customize these dictionaries and create new ones for other cultures. In addition, you can create dictionaries for the custom captions/messages that are used in a particular application only. Read below to learn how to create, customize and link dictionaries to your applications.

Watch Video

Cover Your App by Keys

In your application's HTML view templates, find the text/messages that you want to localize and replace it/them with keys. Write keys in the following way: @textKey, where textKey is the text to be localized that is transformed to a camel case. For instance, here is the HTML markup that contains text that will be displayed on the rendered view as is.

HTML
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">Bill Total:</div>
        <div id="billTotalInput" class="dx-field-value" data-bind="dxNumberBox: {
            value: billTotal,
            placeholder: 'Type here...',
            valueChangeEvent: 'keyup',
            min: 0
        }"></div>
    </div>
</div>

And here is the HTML markup where the text to be displayed on the view is replaced with keys.

HTML
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">@billTotal:</div>
        <div id="billTotalInput" class="dx-field-value" data-bind="dxNumberBox: {
            value: billTotal,
            placeholder: '@typeHere...',
            valueChangeEvent: 'keyup',
            min: 0
        }"></div>
    </div>
</div>

In addition, you can call the Globalize.formatMessage function in JavaScript code to return a string of text as localized to the current locale.

JavaScript
var textToDisplay = Globalize.formatMessage(Key_AppTitle);

The parameter for the formatMessage function is a key that identifies the text to translate.

Generate a Dictionary for Your App

Use the DevExpress.localization.message.getDictionary() utility to generate a dictionary for your application. Run this utility in the browser's console. Choose the required frame in the console (e.g., the top frame) so that the DevExpress namespace is available.

Localization_getDictionary

This utility gathers all the @-keys in HTML code of the application as well as all the @-keys found in the referenced libraries. The return value of this utility is an object whose fields represent the found keys. The field values are the strings that are converted from the keys. Copy the field-value pairs that represent the keys that are specified in this certain application to the clipboard.

Create a JavaScript file giving the localization.XX.js name to it, replacing XX with the identifier of the required locale. Call the Globalize.loadMessages function in it. Pass an object containing a field named after the required locale. For example, "en". Paste the field-value pairs copied to the clipboard to the object assigned to the created field.

JavaScript
Globalize.loadMessages({
    "en": {
        "billTotal": "Bill Total",
        "typeHere": "Type here",
        //...
    }
});
NOTE
If you generated a default dictionary for your application, but then added more keys to the application, call the getDictionary utility with true passed as a parameter. The returned object will include only the keys that are not contained in the application's dictionaries.

Create App Dictionaries for Locales

Using the created dictionary as a base, create dictionaries for different locales. For this purpose, do the following.

  • Make a copy of the localization.XX.js file and rename it replacing XX with the required locale identifier.

  • Modify the Globalize.loadMessages function call. Apply the following modifications to the Globalize.loadMessages function call.

  • Rename the field of an argument object passed to this function using the required locale identifier.
  • Provide the corresponding translation for the keys.

    JavaScript
    Globalize.loadMessages({
        "de": {
            "billTotal": "Rechnungsbetrag",
            "typeHere": "Hier eingeben"
        }
    });

Modify Predefined Dictionaries

In addition to the application dictionaries that include text/messages used only in a specific application, you can use the predefined dictionaries that come with DevExtreme. They include the captions and messages such as 'Back', 'Cancel', 'Select', 'Loading', 'Search' - these can be added to your app with a DevExtreme widget or layout. The predefined dictionaries are available in the Lib/js/localization folder within your DevExtreme package.

If the set of predefined dictionaries does not include a dictionary for a locale you need, do the following.

  • Create a single-page application containing the following code that will create a dictionary file based on an existing dictionary data.

    HTML
    <!DOCTYPE html>
    <html>
        <head>
            <script src="libs/js/jquery-2.2.3.js"></script>
            <script src="libs/js/dx.all.debug.js"></script>
            <script> 
            $(function() {
              var data = { en: DevExpress.localization.message.getDictionary() },
                  dataString = encodeURIComponent(JSON.stringify(data, null, "\t"));
              $("a").attr("href", "data:text/plain;charset=utf-8," + dataString);
            });
            </script>
        </head>
        <body>
        <a download="dx.all.en.json">Download localization messages JSON</a>
        </body>
    </html>

    This application will create the dx.all.en.json (dx.web.en.json, dx.mobile.en.json) file based on dictionary data loaded from the dx.all.en.js (dx.web.en.js, dx.mobile.en.js) library. The dictionary data can be obtained using the following method.

    JavaScript
    DevExpress.localization.message.getDictionary();
  • Open the application and click the "Download localization message's JSON" link, which will invoke the "Save As" dialog. Specify the file name (dx.mobile.XX.json, dx.web.XX.json or dx.all.XX.json), replacing XX with the identifier of the required locale. For example, dx.mobile.es.json. Save the file.

    NOTE
    The suggested names for your dictionary files are not important. You can give them other names if required.
  • Open the created file for editing and replace the "en" identifier with the identifier of the required locale. For example "es".

    {
        "es": {
            "Yes": "Yes",
            "No": "No",
            . . .
        }
    }
  • Provide an object containing the corresponding translation for the keys.

    {
        "es": {
            "Yes": "Si",
            "No": "No",
            . . .
        }
    }

After the .json file is updated, you can load its data using an AJAX request.

JavaScript
$.when(
    $.get("dx.all.es.json")
).then(function(data){
    Globalize.loadMessages(data);
});

Extend Predefined Dictionaries

You can extend the predefined dictionaries by the key-value pairs to provide localization for custom captions/messages. For instance, you can provide localized grid column captions by using the keys that are specially added to predefined dictionaries.

JavaScript
Globalize.loadMessages({
    de: {
        //...
        "column_name": "Vorname"
    }
});
JavaScript
var dataGridOptions = {
    dataSource: orders,
    columns: [
        {
            dataField: "Name",
            caption: Globalize.formatMessage(column_name);
        }, 
        //...
    ]
}

Link All Dictionaries

Within the index.html file (the main page of your application), add links to the following files.

  • globalize libraries
    Libraries containing the globalize functionality, which can be found in the Lib/js folder within your DevExtreme Package. The list of libraries is presented below.

    • cldr.js
    • cldr/event.js
    • cldr/supplemental.js
    • globalize.js
    • globalize/message.js
    • globalize/number.js
    • globalize/currency.js
    • globalize/date.js
  • dx.mobile.js (dx.all.js or dx.web.js)
    A predefined dictionary for the required locale.

  • localization.XX.js
    Your application's dictionary for the required locale.

Take a look below for an example of links in code.

HTML
<script type="text/javascript" src="/js/cldr.js"></script>
<script type="text/javascript" src="/js/cldr/event.js"></script>
<script type="text/javascript" src="/js/cldr/supplemental.js"></script>
<script type="text/javascript" src="/js/globalize.js"></script>
<script type="text/javascript" src="/js/globalize/message.js"></script>
<script type="text/javascript" src="/js/globalize/number.js"></script>
<script type="text/javascript" src="/js/globalize/currency.js"></script>
<script type="text/javascript" src="/js/globalize/date.js"></script>
<script type="text/javascript" src="js/dx.mobile.js"></script>
<script type="text/javascript" src="js/localization/dx.mobile.de.js"></script>
<script type="text/javascript" src="js/localization/dx.mobile.ja.js"></script>
<script type="text/javascript" src="js/localization/dx.mobile.ru.js"></script>
<script type="text/javascript" src="js/localization/localization.de.js"></script>
<script type="text/javascript" src="js/localization/localization.ja.js"></script>
<script type="text/javascript" src="js/localization/localization.ru.js"></script>

For the information on dependencies between Globalize modules, refer to the Dependencies section of Globalize documentation.

NOTE
Dictionary scripts must be linked in the same order as presented in the example above. DevExtreme scripts must be linked above dictionary scripts.

Use AJAX requests to load the required CLDR data. You can download this data (stored in .json files) from the Unicode-CLDR repository.

JavaScript
$.when(
    $.getJSON("lib/js/cldr/main/de/ca-gregorian.json"),
    $.getJSON("lib/js/cldr/main/de/numbers.json"),
    $.getJSON("lib/js/cldr/main/de/currencies.json"),
    $.getJSON("lib/js/cldr/supplemental/likelySubtags.json"),
    $.getJSON("lib/js/cldr/supplemental/timeData.json"),
    $.getJSON("lib/js/cldr/supplemental/weekData.json"),
    $.getJSON("lib/js/cldr/supplemental/currencyData.json"),
    $.getJSON("lib/js/cldr/supplemental/numberingSystems.json")
).then(function () {
    //The following code converts the got results into an array
    return [].slice.apply( arguments, [0] ).map(function( result ) {
        return result[ 0 ];
    });
}).then(
    Globalize.load //loads data held in each array item to Globalize
).then(function(){
    //initialize your application here
})

To learn which .json data is required by each Globalize module, refer to the CLDR content section of Globalize documentation.

Set Application Locale

If you add several dictionaries to the application, specify which one of them is to be used when running this application. For this purpose, detect the language of the browser in which the application is running and set the appropriate locale as demonstrated in the code below.

JavaScript
Globalize.locale(navigator.language || navigator.browserLanguage);

This line of code should be written somewhere in the index.js file of your application, before creating the HtmlApplication object.

If globalize libraries are not found for the specified locale, the neutral English locale "en" is used by default.