DevExtreme Angular - 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 17.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.

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.

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

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

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.

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.

DevExpress.localization.loadMessages({
    "en": {
        "billTotal": "Bill Total",
        "typeHere": "Type here",
        //...
    }
});

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

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

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

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 Using Globalize article.

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.

<!--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>

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

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

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.

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

In modular approach, use the following code.

var localization = require("devextreme/localization");
localization.locale(navigator.language || navigator.browserLanguage);