Localization

DevExtreme SPA framework provides an easy way to localize your applications. 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 Lib\js\localization folder in the DevExtreme zip archive or in the folder where you have installed DevExtreme, which is C:\Program Files (x86)\DevExpress 16.2\DevExtreme\Sources by default. 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.

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>

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 localization.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
DevExpress.localization.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 localization.loadMessages function call. Apply the following modifications to the localization.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
    DevExpress.localization.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 in the DevExtreme zip archive or in the folder where you have installed DevExtreme, which is C:\Program Files (x86)\DevExpress 16.2\DevExtreme\Sources by default.

If the set of predefined dictionaries does not include a dictionary for a locale you need, you can create a dictionary file based on an existing dictionary data stored in the Lib\js\localization folder. Create a new file based on dx.messages.en.js, replacing the "en" locale identifier in it's 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 the 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>

Extend Predefined Dictionaries

If you need to localize custom captions/messages in your application, use Globalize or another 3rd-party localization library. To learn how to localize messages using Globalize, refer to the Localization - Use Globalize article.

Link All Dictionaries

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

  • 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
<!--DevExtreme library-->
<script type="text/javascript" src="js/dx.web.js"></script>

<!--DevExtreme dictionaries-->
<script type="text/javascript" src="js/localization/dx.messages.en.js"></script>
<script type="text/javascript" src="js/localization/dx.messages.de.js"></script>
<script type="text/javascript" src="js/localization/dx.messages.ja.js"></script>
<script type="text/javascript" src="js/localization/dx.messages.ru.js"></script>

<!--Application dictionaries-->
<script type="text/javascript" src="js/localization/localization.en.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>
NOTE
Dictionary scripts must be linked in the same order as those presented in the example above. DevExtreme scripts must be linked above dictionary scripts.

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

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