Localization

Jun 18, 2025
5 minutes to read

Localization set-up consists of the following parts:

Localize date, number, and currency values. There are two methods to do this:
Localize messages. To do this, use dictionaries that 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 a custom dictionary.
Set the locale.

This document contains step-by-step instructions for the Intl and Globalize methods.

Intl

To set up localization based on the Intl object, follow the steps below.

Step 1. Reference Dictionaries

Open the file where DevExtreme scripts are referenced (for example, the _Layout.cshtml file) and reference dictionaries before the closing head tag:

_Layout.cshtml (.vbhtml)

cshtml

<head>
...
    @* reference dictionaries *@
    <script src="~/Scripts/localization/dx.messages.de.js"></script>
    <script src="~/Scripts/localization/dx.messages.es.js"></script>
</head>

Step 2. Set the Locale

You should set the locale to apply string translation and data formatting. To do this, add the script block to Razor files where you configure DevExtreme 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:

_Layout.cshtml (.vbhtml)

html

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

Note

Demo: Using Intl

Globalize

Important

The Globalize package is outdated and potentially unsafe. Use Globalize at your own risk. We recommend switching to Intl for a more secure solution.

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 DevExtremeBundleConfig.cs (.vb) file.

DevExtremeBundleConfig.cs
DevExtremeBundleConfig.vb

public class DevExtremeBundleConfig {
    public static void RegisterBundles(BundleCollection bundles) {
        var scriptBundle = new ScriptBundle("~/Scripts/DevExtremeBundle");
        // ... 
        scriptBundle.Include("~/Scripts/cldr.js");
        scriptBundle.Include("~/Scripts/cldr/event.js");
        scriptBundle.Include("~/Scripts/cldr/supplemental.js");
        scriptBundle.Include("~/Scripts/cldr/unresolved.js");

        scriptBundle.Include("~/Scripts/globalize.js");
        scriptBundle.Include("~/Scripts/globalize/message.js");
        scriptBundle.Include("~/Scripts/globalize/number.js");
        scriptBundle.Include("~/Scripts/globalize/currency.js");
        scriptBundle.Include("~/Scripts/globalize/date.js");
        // ... 
    }
}

Public Class DevExtremeBundleConfig
   Public Shared Sub RegisterBundles(ByVal bundles As BundleCollection)
        Dim scriptBundle = new ScriptBundle("~/Scripts/DevExtremeBundle");
        ' ...
        scriptBundle.Include("~/Scripts/cldr.js")
        scriptBundle.Include("~/Scripts/cldr/event.js")
        scriptBundle.Include("~/Scripts/cldr/supplemental.js")
        scriptBundle.Include("~/Scripts/cldr/unresolved.js")

        scriptBundle.Include("~/Scripts/globalize.js")
        scriptBundle.Include("~/Scripts/globalize/message.js")
        scriptBundle.Include("~/Scripts/globalize/number.js")
        scriptBundle.Include("~/Scripts/globalize/currency.js")
        scriptBundle.Include("~/Scripts/globalize/date.js")
        ' ...
    End Sub
End Class

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.

The corresponding code lines are commented out, you need to uncomment them.

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:
Copy the cldr-data directory to the your project’s 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.

The code below demonstrates the Home controller that has the CldrData action. This action loads CLDR JSONs for German and Spanish locales from the node_modules/cldr-data directory and sets German as the default locale:

csharp

public class HomeController : Controller {
    public IActionResult Index() {
        return View();
    }

    public ActionResult CldrData() {
        return new DevExtreme.AspNet.Mvc.CldrDataScriptBuilder()
            .SetCldrPath("~/cldr-data")
            .SetInitialLocale("de")
            .UseLocales("de", "es")
            .Build();
    }
}

Public Class HomeController
    Inherits Controller
    Public Function Index() As ActionResult
        Return View()
    End Function

    Public Function CldrData() As ActionResult
        Return New DevExtreme.AspNet.Mvc.CldrDataScriptBuilder() _
            .SetCldrPath("~/cldr-data") _
            .SetInitialLocale("de") _
            .UseLocales("de", "es") _
            .Build()
    End Function
End Class

Step 4. Reference Dictionaries and Load CLDR Data

Open the file where DevExtreme scripts are referenced. Typically, it is the _Layout.cshtml (.vbhtml) file.
Before the closing head tag:

Note

Demo: Using Globalize

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 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.
For Globalize, call the Globalize.locale method and specify navigator.language as a parameter.