Localization
- 5 minutes to read
This document shows two methods you can use to localize DevExtreme-based ASP.NET Controls. These methods are based on:
- the Intl object - a localization mechanism that is integrated into most modern browsers.
- an external Globalize library that does not depend on the browser.
Localization set-up consists of the following parts:
- Reference DevExtreme localization scripts (used to localize date, number, and currency values).
- Reference dictionaries (contain localized messages for different languages). The DevExtreme distribution includes predefined dictionaries (the dx.messages.[lang].js files in your project’s wwwroot/js/devextreme/localization directory). Use these files as is or as a base for custom dictionary.
- Set the locale.
The Intl localization is easier to configure while the Globalize localization requires that you obtain CLDR data files and add code to load them.
Intl
To set up localization based on the Intl object, follow the steps below.
Step 1. Reference the Intl Module and Dictionaries
Open the file where DevExtreme scripts are referenced (typically, it is the _Layout.cshtml file). Before the closing head
tag, reference the DevExtreme-Intl module and dictionaries:
<head>
...
@* reference the Intl module *@
<script src="https://unpkg.com/devextreme-intl/dist/devextreme-intl.min.js"></script>
@* reference dictionaries *@
<script src="~/js/devextreme/localization/dx.messages.de.js"></script>
<script src="~/js/devextreme/localization/dx.messages.es.js"></script>
</head>
Note
Although we have plans to integrate Intl into our project templates in future releases, the current version of templates uses Globalize. To prevent conflicts with Intl, remove links to Globalize and CLDR files from the project. You can find these links in the _Layout.cshtml or bundleconfig.json file.
Step 2. Set the Locale
To apply string translation and data formatting, you need to set the locale. To do this, add the script
block to Razor files where you configure DevExtreme-based controls or to the project’s layout that applies to all pages in the application, and call the DevExpress.localization.locale method. For example, the following code sets German as the default locale:
<script>
DevExpress.localization.locale("de");
</script>
You can also set the locale based on the client locale or dynamically (for example, your application contains a control that allows to switch a language, and the locale can depend on the selected language).
View the Using Intl demo.
Globalize
Follow the steps below to set up localization based on the Globalize library.
Step 1. Link Globalize Modules and CLDR Scripts
Ensure the Globalize modules and CLDR scripts are linked in the _Layout.cshtml or bundleconfig.json file.
<head>
//...
<script src="~/js/devextreme/cldr.js"></script>
<script src="~/js/devextreme/cldr/event.js"></script>
<script src="~/js/devextreme/cldr/supplemental.js"></script>
<script src="~/js/devextreme/cldr/unresolved.js"></script>
<script src="~/js/devextreme/globalize.js"></script>
<script src="~/js/devextreme/globalize/message.js"></script>
<script src="~/js/devextreme/globalize/number.js"></script>
<script src="~/js/devextreme/globalize/currency.js"></script>
<script src="~/js/devextreme/globalize/date.js"></script>
//...
</head>
These files are added and linked in the project in the following cases:
- You used our project templates to create a project.
- You used the Add DevExtreme to the Project command for Visual Studio projects.
- You followed these instructions for non Visual Studio projects.
Step 2. Obtain CLDR Data Files
The Globalize library requires CLDR data files. To get and add these files to the project:
Ensure Node.js is installed on your computer.
Create a temp directory anywhere on your computer.
Open the console from this directory and run the following commands:
npm init -y npm i cldr-data
You can find the downloaded CLDR JSON files in <temp_directory>/node_modules/cldr-data.
Copy the cldr-data directory to the <your_project>/wwwroot directory.
Note
The cldr-data directory contains data for a large number of languages. To reduce the directory’s size, you can remove unnecessary languages data from the cldr-data/main subdirectory.
Step 3. Add Code that Loads CLDR Data for Required Cultures and Sets the Default Locale
To load CLDR JSON files, open your controller’s code and create an action method that uses the CldrDataScriptBuilder helper.
Important
If you use Razor Pages, you should first create a controller.
The code below demonstrates the Home
controller that has the CldrData
action. This action loads CLDR JSONs for German and Russian locales from the node_modules/cldr-data directory and sets German as the default locale:
public class HomeController : Controller {
public IActionResult Index() {
return View();
}
public ActionResult CldrData() {
return new DevExtreme.AspNet.Mvc.CldrDataScriptBuilder()
.SetCldrPath("~/wwwroot/cldr-data")
.SetInitialLocale("de")
.UseLocales("de", "es")
.Build();
}
}
You can also set the locale based on the client locale or dynamically (for example, your application contains a control that allows to switch a language, and the locale can depend on the selected language).
Step 4. Reference Dictionaries and Load CLDR Data
Open the file where DevExtreme scripts are referenced. Typically, it is the _Layout.cshtml file.
Before the closing
head
tag:- Add a script element that loads CLDR data from the
CldrData
action method. To do this, use the@Url.Action
helper. The third argument passed to it ensures that the browser caches the CLDR data. - Reference dictionaries.
<head> ... @* execute the CldrData action method *@ <script src="@Url.Action("CldrData", "Home", new { t = CldrDataScriptBuilder.GetCacheParam() })"></script> @* reference dictionaries *@ <script src="~/js/devextreme/localization/dx.messages.de.js"></script> <script src="~/js/devextreme/localization/dx.messages.es.js"></script> </head>
- Add a script element that loads CLDR data from the
View the Using Globalize demo.
Custom Dictionaries
Here are a few situations when you may need a custom dictionary:
- There is no predefined dictionary for the language you require.
- You need to change translations.
- You need to add new messages.
To create and use a custom dictionary:
- Create a copy of a predefined dictionary.
- Update or add strings as necessary.
- Reference the resulting file as you would do with a predefined dictionary.
Auto Detect the Locale
You can configure controls so that they automatically detect the client browser’s locale and apply the corresponding UI translation and data formatting. To do this, add the script
code block provided below to Razor files where you configure DevExtreme-based controls or to a project’s layout that applies to all pages in the application.
For Intl, call the DevExpress.localization.locale method and specify
navigator.language
as a parameter.<script> DevExpress.localization.locale(navigator.language); </script>
For Globalize, call the
Globalize.locale
method and specifynavigator.language
as a parameter.<script> Globalize.locale(navigator.language); </script>