The requested page is not available for the requested platform. You are viewing the content for Default platform.

Localization

  • 5 min to read

Follow the steps below to adapt DevExtreme-based ASP.NET Core controls to linguistic and regional differences.

Note

These instructions are also available in the Localization video.

Reference Localization Modules

You can use Intl or Globalize to set up localization.

Intl

Follow the steps to set up localization using the Intl object:

  1. Create a @section in a Razor file (.cshtml) where you configure controls and reference the devextreme-intl module in it.

    The following code creates such a section (Localization) in the Index.cshtml file:

    
    @using DevExtremeAspNetCoreApp1.Models
    
    // creates the section that references the Intl module
    @section Localization {
        <script src="https://unpkg.com/devextreme-intl/dist/devextreme-intl.min.js"></script>
    }
    
    <h2>Home</h2>
    
    @(Html.DevExtreme()
        .Button() // creates the Button control
        // ...
    )
    
  2. Open the Views/Shared/_Layout.cshtml or Pages/_Layout.cshtml file and add the following command before the closing head tag:

    <head>
        ...
        // renders the Localization section
        @RenderSection("Localization", false)
    </head>
    
Note

Our project templates use Globalize to localize controls. To prevent possible conflicts with Intl, remove links to Globalize and CLDR files from the project. You can find these links in the Views/Shared/_Layout.cshtml or bundleconfig.json file.

View the Using Intl demo.

Globalize

Follow the steps below to set up localization using the Globalize library.

Make sure that the Globalize modules and CLDR scripts are linked in the Views/Shared/_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:

Get CLDR Data

To get and add CLDR JSON files to the project:

  1. Ensure that Node.js is installed on your computer.

  2. Open your project's directory in the File Explorer.

  3. 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 the directory <project_name>/node_modules/cldr-data.

    Note

    If your project is under source control, add the node_modules directory to the project's ignore list. For example, if you use git, add this directory to your .gitignore file.

Load CLDR Data

  1. In a controller, create an action method that uses CldrDataScriptBuilder to load CLDR JSON files.

    Important

    If you use Razor Pages, first create a controller.

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

    public class HomeController : Controller
    {
        public IActionResult Index()
        {
            return View();
        }
    
        public ActionResult CldrData()
        {
            return new DevExtreme.AspNet.Mvc.CldrDataScriptBuilder()
            .SetCldrPath("~/node_modules/cldr-data")
            .SetInitialLocale("de")
            .UseLocales("de", "es")
            .Build();
        }
    }
    
  2. In a Razor file (.cshtml) where you configure controls, create a @section and 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.

    The following example demonstrates how to create such a section (Localization) in the Index.cshtml file:

    @using DevExtremeAspNetCoreApp1.Models
    
    // creates the section that executes the CldrData action method
    @section Localization {
        <script src="@Url.Action("CldrData", "Home", new { t = CldrDataScriptBuilder.GetCacheParam() })"></script>
    }
    
    <h2>Home</h2>
    
    @(Html.DevExtreme()
        .Button() // creates the Button control
        // ...
    )
    
  3. In the Views/Shared/_Layout.csthml or Pages/_Layout.cshtml file, add the command that renders the created section before the closing head tag.

    <head>
        ...
        // renders the Localization section
        @RenderSection("Localization", false)
    </head>
    

View the Using Globalize demo.

Reference Dictionaries

Predefined Dictionaries

DevExtreme is shipped with several predefined dictionaries (dx.messages.[lang].js files) that you can use "as is" or as a base for your custom dictionary. You can find them in your project's wwwroot/js/devextreme/localization directory.

Reference a predefined dictionary in the Localization section.

@section Localization {
    // references the Intl module or executes the CldrData action method
    // ...
    // references dictionaries
    <script src="~/js/devextreme/localization/dx.messages.de.js"></script>
    <script src="~/js/devextreme/localization/dx.messages.es.js"></script>
}

Custom Dictionaries

To create a custom dictionary:

  1. Copy one of the predefined dictionaries and give it a name, for example, dx.messages.es.js for Spanish translation.
  2. Translate messages in the dictionary to the required language.

Finally, reference the custom dictionary in the Localization section like predefined dictionaries.

Auto Detect the Locale

You can configure controls to detect the locale automatically, based on a web browser's locale.

  1. Open the Razor file (.cshtml) where you configure controls.
  2. Add a <script> tag to the bottom.
  3. Set the current locale:

    • If you use Intl, call the DevExpress.localization.locale method.

      // ...
      
      // sets the current locale
      <script>
          DevExpress.localization.locale(navigator.languages && navigator.languages[0] ||
              navigator.language ||
              navigator.userLanguage);
      </script>
      
    • If you use Globalize, call the Globalize.locale method.

      // ...
      
      // sets the current locale
      <script>
          Globalize.locale(navigator.languages && navigator.languages[0] ||
              navigator.language ||
              navigator.userLanguage);
      </script>