Localization

DevExtreme provides an easy way to localize UI widgets. It uses the localization module to load 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 [Sources]/Lib/js/localization folder within the DevExtreme zip archive or in the folder where you have installed DevExtreme. For the modular approach, the dictionaries are provided as json files stored in the node_modules/devextreme/localization/messages folder. You can customize these dictionaries and create new ones for other cultures.

To localize dates, numbers and currencies, you can use third-party libraries - Intl or Globalize. In addition DevExtreme allows you use Globalize library to localize messages.

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. DevExtreme includes the following dictionary files providing the localization of desktop, mobile and multi-purpose UI widgets for the ru, ja, de and en locales, respectively.

  • dx.messages.ru.js
  • dx.messages.ja.js
  • dx.messages.de.js
  • dx.messages.en.js
NOTE
You are not required to link the "en" locale dictionary because it is already included in DevExtreme libraries. You can use the dx.messages.en.js dictionary to create custom dictionaries for other locales based on this dictionary.

The predefined dictionaries are available in the [Sources]/Lib/js/localization folder within the DevExtreme zip archive or in the folder where you have installed DevExtreme.

Create Dictionaries for Other Locales

If the set of predefined dictionaries does not include a dictionary for a locale you need, you can create a dictionary file based on existing dictionary data stored in the [Sources]/Lib/js/localization folder within the DevExtreme zip archive or in the folder where you have installed DevExtreme.

Create a new file based on dx.messages.en.js, replacing the "en" locale identifier in its name with the identifier of the required locale. For example, "es" (dx.messages.es.js). Open the newly created file for editing and replace the "en" locale identifier in the file content as well.

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

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

After the .js file is updated, you can link it to your application and use in the same way as other dictionary files.

HTML
<script type="text/javascript" src="js/dx.web.js"></script>
<script type="text/javascript" src="js/localization/dx.messages.es.js"></script>

In the modular approach, you can define a dictionary in a json file created on the base of the en.json located in the npm_modules/devextreme/localization/messages folder. Rename it replacing the "en" identifier with the required locale identifier ("es.json"), replace the identifier within the created file and provide an object containing the translation for keys as described above.

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/dx.web.js"></script>
<script type="text/javascript" src="js/localization/dx.messages.de.js"></script>
NOTE
Dictionary scripts must be linked in the same order as they were presented in the example above. DevExtreme scripts must be linked above dictionary scripts.

If you are using the modular approach, link the localization module as demonstrated below.

JavaScript
//Loads the localization modules
var localization = require("devextreme/localization");

//Loads dictionary for the "de" locale
var deMessages = require("devextreme/localization/messages/de.json!json");

//Loads messages from the dictionary.
localization.loadMessages(deMessages);
NOTE
The way you link modules depends on the selected module loader (for example, jspm, Webpack or others).

If you are using Globalize, refer to the Localization - Use Globalize article to learn how to link Globalize modules.

For information on linking modules required for Intl localization, refer to Intl documentation.

Set Application Locale

To change the default locale of your application, detect the language of the browser in which the application is running and set the appropriate locale as demonstrated in the code below.

JavaScript
DevExpress.localization.locale(navigator.language || navigator.browserLanguage);

In the modular approach, use the following code.

JavaScript
var localization = require("devextreme/localization");
localization.locale(navigator.language || navigator.browserLanguage);
NOTE
Set locale only after the DevExtreme library is loaded.