Localization

DevExtreme provides an easy way to localize UI widgets. 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 locales extensions are provided by separate dictionary files. These dictionaries can be found in the [Sources]/Lib/js/localization folder within your DevExtreme package. You can customize these dictionaries and create new ones for other cultures. Read below to learn how to use, customize and create dictionaries in your applications.

Use Predefined Dictionaries

DevExtreme comes with ready-to-use predefined dictionaries. These dictionaries include all the captions, titles and messages that are used in DevExtreme UI widgets. Here is a list of the currently supplied dictionaries.

  • dx.web.ru.js, dx.web.ja.js and dx.web.de.js
    Comes with the DevExtreme Web and DevExtreme Complete kits. Includes the localization of desktop and multi-purpose UI widgets for the ru, ja and de locales, respectively.

  • dx.mobile.ru.js, dx.mobile.ja.js and dx.mobile.de.js
    Comes with the DevExtreme Mobile and DevExtreme Complete kits. Includes localization of mobile and multi-purpose UI widgets for the ru, ja and de locales, respectively.

  • dx.all.ru.js, dx.all.ja.js and dx.all.de.js
    Comes with the DevExtreme Complete kit. Includes the localization of desktop, mobile and multi-purpose UI widgets for the ru, ja and de locales, respectively.

The predefined dictionaries are available in the [Sources]/Lib/js/localization folder within your DevExtreme package.

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: {
        //...
        "gridcolumn_name": "Vorname"
    }
});
JavaScript
var dataGridOptions = {
    dataSource: orders,
    columns: [
        {
            dataField: "Name",
            caption: Globalize.formatMessage("gridcolumn_name");
        }, 
        //...
    ]
}

Create Dictionaries for Other Locales

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 messages 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);
});

Link Dictionaries

Add the required DevExtreme localization files to your project. Add links to these files within the main page of your application.

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>

For 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.

Also, you need to load the required CLDR data. Refer to the Globalize documentation to learn how to load CLDR data to Globalize. For example, you can load it using AJAX requests to load the required CLDR data.

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
})

You can download this data (stored in .json files) from the Unicode-CLDR repository.

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);
NOTE
Set locale only after the DevExtreme library is loaded.