Localization

The DevExtreme SPA framework provides an easy way to localize your applications. It uses the globalize library and extends its cultures by translations of specific captions/messages such as 'Back', 'Cancel', 'Select', 'Loading', 'Search' and others to the corresponding languages. The DevExtreme culture extensions are provided by separate dictionary files. These dictionaries can be found in the Lib/js/localization folder within the product location folder. 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.localize function in JavaScript code to return a string of text as localized to the current culture.

JavaScript
var textToDisplay = Globalize.localize(Key_AppTitle);

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

Generate a Default Dictionary for Your App

Use the DevExpress.localization.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.default.js name to it. Call the Globalize.addCultureInfo function in it. Pass 'default' as the first parameter and an object with the messages field as the second parameter. Paste the field-value pairs copied to the clipboard to the object assigned to the messages field.

JavaScript
Globalize.addCultureInfo("default", {
    messages: {
        "billTotal": "Bill Total",
        "typeHere": "Type here",
        //...
    }
});

The localization.default.js file is a default dictionary of your application.

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.

You can extend this dictionary with the keys that you specified in the JavaScript code of your application using the Globalize.localize function.

JavaScript
Globalize.addCultureInfo("default", {
    messages: {
        "billTotal": "Bill Total",
        "typeHere": "Type here",
        //...
        "Key_AppTitle": "Application Title"
    }
});

Create App Dictionaries for Cultures

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

  • Make a copy of the localization.default.js file and rename it to localization.XX.js where XX is a culture identifier.

  • Modify the addCultureInfo function call. Pass the culture's identifier as the first parameter and an object with the messages field set to the object providing the corresponding translation for the keys.

    JavaScript
    Globalize.addCultureInfo("fr", {
        messages: {
            "billTotal": "Facture Totale",
            "typeHere": "Entrez ici"
        }
    });

Modify Predefined Dictionaries

In addition to the application dictionaries that include text/messages used in a particular application only, 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 the product location folder. You can modify the predefined dictionaries replacing text translation with your own one.

If the set of predefined dictionaries does not include a dictionary for a particular culture, do the following.

  • Make a copy of the dx.phonejs.XX(dx.all.XX) file and rename it replacing XX with the identifier of the required culture.

  • Modify the addCultureInfo function call. Pass the culture's identifier as the first parameter and an object with the messages field that is set to the object providing the corresponding translation for the keys.

    JavaScript
    Globalize.addCultureInfo("fr", {messages: {
        "Yes": "Oui",
        "No": "Pas",
        //...
    }});

Link All Dictionaries

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

  • globalize.min.js
    The globalize library, which can be found in the Lib/js folder within the product location folder.
  • localization.default.js
    Your application's default dictionary.
  • globalize.culture.XX.js
    The globalize dictionary for the required culture. You can find it on GitHub, for instance.
  • dx.phonejs.XX.js(dx.all.XX)
    A predefined dictionary for the required culture.
  • localization.XX.js
    Your application's dictionary for the required culture.

Here is how the links can look in code.

HTML
<script type="text/javascript" src="js/globalize.min.js"></script>
<script type="text/javascript" src="js/localization.default.js"></script>

<script type="text/javascript" src="js/fr/globalize.culture.fr.js"></script>
<script type="text/javascript" src="js/fr/dx.phonejs.fr.js"></script>
<script type="text/javascript" src="js/fr/localization.fr.js"></script>

NOTE: The globalize.culture.XX.js dictionary must be linked above the corresponding PhoneJS dictionary.

NOTE: All dictionary files must be linked above the PhoneJS library link.

NOTE: The names for the dictionary files suggested in this article are not important. You can give them other names if required.

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 culture as demonstrated in the code below.

JavaScript
Globalize.culture(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 culture, the neutral English culture "en" is used by default. This culture's dictionary is extended by the default dictionary of your application.