Localize ASP.NET Core Dashboard Control

Jan 16, 2024
5 minutes to read

You can localize your applications - update their UI to match certain culture and language settings:

Translate UI element captions to a different language: dialog boxes, buttons, menu items, error messages, and so on (localization).
Format numbers, dates, and currencies according to specific culture settings (globalization).

web-dashboard-localization

View Example: Dashboard for ASP.NET Core - Localization

Localize UI

Satellite Resource Assemblies

For ASP.NET Core 6+, localize an ASP.NET Core Dashboard application with satellite resource assemblies.

Add Predefined Satellite Assemblies

We published NuGet packages with predefined satellite resource assemblies for the following cultures:

German: DevExpress.AspNetCore.Dashboard.de
Spanish: DevExpress.AspNetCore.Dashboard.es
Japanese: DevExpress.AspNetCore.Dashboard.ja

Follow the steps below to add the above-mentioned resources for cultures:

In Visual Studio, open NuGet Package Manager for the solution.
In the invoked manager, select the DevExpress package source. Find the DevExpress.AspNetCore.Dashboard.XX NuGet package with the required culture and install it (for example, DevExpress.AspNetCore.Dashboard.es).

Add Satellite Assemblies for Other Cultures

You can add the assemblies for other cultures to your ASP.NET Core application. Follow the steps below to add the resources for French (fr culture):

Go to the DevExpress Localization Service to download satellite assemblies for DevExpress .NET controls that correspond to other cultures. Ensure that the version of the satellite assemblies (for instance, v20.2) matches the version of the DevExpress Dashboard package in the project.

Modules to translate:
- Dashboard.Core
- Dashboard.Web
- DataAccess
- Web.Resources
Create a subdirectory in the application’s EXE file directory (usually in the bin\Debug\netX.X\ subdirectory) with the name that corresponds to the newly generated resource culture (for example, bin\Debug\netX.X\fr - to translate your application into French).
Unpack the archive with resources generated by the DevExpress Localization Service and copy all the *.v23.2.resources.dll files to the newly created subdirectory.

Configure Localization Middleware

After you add assemblies, configure the Localization Middleware:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    // ...
    var supportedCultures = new[] { "en-US", "es", "fr" };
    app.UseRequestLocalization(new RequestLocalizationOptions()
        .SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures));

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseDevExpressControls();

    app.UseRouting();
    app.UseEndpoints(endpoints => {
        endpoints.MapDashboardRoute("dashboardControl", "DefaultDashboard");
        endpoints.MapRazorPages();
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

When you launch the application, you can pass the culture and ui-culture query string parameters to the application’s URL. The following example sets the Spanish culture:

http://localhost:5000/?culture=es&ui-culture=es

You can also specify both the language and region (for example, es-MX for Spanish/Mexico).

UI Localization Client

The UI Localization Client is a cross-platform utility that allows you to quickly identify non-translated strings of DevExpress UI controls and translate them during a debug session. The utility automatically generates a RESX file(s) with translated resources and adds it to the project. Note that the UI Localization Client loads all Web Dashboard resource strings at once, without reflecting your interaction with the UI.

For more information refer to the following topic: UI Localization Client.

The resource strings for the Web Dashboard Control are located in the following localization containers:

DevExpress.DashboardWeb.Localization.LocalizationContainer: Contains localization strings specific only to the Web Dashboard Control.
DevExpress.Utils.Localization.CoreLibraryResources: Contains cross-platform localization strings used in the Web Dashboard Control.
DevExpress.Web.Resources.Localization.LocalizationContainer: Contains localization strings common to DevExpress Web Components used in the Web Dashboard Control.

Troubleshooting

If you followed the instructions in the UI Localization Client topic and translated resources do not appear on your web page, try clearing browser cache.
If you followed the instructions in the UI Localization Client topic and the resource strings do not appear in the UI Localization Client window, call the HandleRequestsFromAllThreads() method at application startup to use localizer objects across all application threads.

Localize Dates, Numbers, and Currencies

Intl

The ASP.NET Core Dashboard control uses Intl as a default way to apply culture-specific formatting. Intl is the short name used to refer to a particular ECMAScript Internationalization API object. The Web Dashboard supports this API out of the box. To localize date, numbers, and currencies, do the following:

Configure the localization middleware.
Handle the OnInitializing(String) event. Call the locale() method and pass the locale as a parameter:
```
function onInitializing(sender) {
    DevExpress.localization.locale('de');
}
```

Globalize

The ASP.NET Core Dashboard control can use Globalize instead of Intl to format dates, numbers, and currencies.

Follow the steps below to use Globalize for culture-specific formatting:

Install the following packages:

npm install globalize@^1.0.1 devextreme-cldr-data@^1.0.2

When you bundle scripts, add the following lines to the bundleconfig.json file:

[
    {
        "outputFileName": "wwwroot/css/site.min.css",
        "inputFiles": [
            "node_modules/ace-builds/css/ace.css",
            "node_modules/ace-builds/css/theme/dreamweaver.css",
            "node_modules/ace-builds/css/theme/ambiance.css",
            "node_modules/devextreme-dist/css/dx.light.css",
            "node_modules/@devexpress/analytics-core/dist/css/dx-analytics.common.css",
            "node_modules/@devexpress/analytics-core/dist/css/dx-analytics.light.css",
            "node_modules/@devexpress/analytics-core/dist/css/dx-querybuilder.css",
            "node_modules/devexpress-dashboard/dist/css/dx-dashboard.light.min.css"
        ],
        "minify": { "enabled": false, "adjustRelativePaths": false }
    },
    {
        "outputFileName": "wwwroot/js/site.min.js",
        "inputFiles": [
            "node_modules/jquery/dist/jquery.min.js",
            "node_modules/knockout/build/output/knockout-latest.js",
            "node_modules/ace-builds/src-min-noconflict/ace.js",
            "node_modules/ace-builds/src-min-noconflict/ext-language_tools.js",
            "node_modules/ace-builds/src-min-noconflict/theme-dreamweaver.js",
            "node_modules/ace-builds/src-min-noconflict/theme-ambiance.js",
            "node_modules/cldrjs/dist/cldr.js",
            "node_modules/cldrjs/dist/cldr/event.js",
            "node_modules/cldrjs/dist/cldr/supplemental.js",
            "node_modules/globalize/dist/globalize.js",
            "node_modules/globalize/dist/globalize/message.js",
            "node_modules/globalize/dist/globalize/number.js",
            "node_modules/globalize/dist/globalize/date.js",
            "node_modules/globalize/dist/globalize/currency.js",
            "node_modules/devextreme-cldr-data/supplemental.js",
            "node_modules/devextreme-cldr-data/es.js",
            "node_modules/devextreme-dist/js/dx.all.js",
            "node_modules/@devexpress/analytics-core/dist/js/dx-analytics-core.min.js",
            "node_modules/@devexpress/analytics-core/dist/js/dx-querybuilder.min.js",
            "node_modules/devexpress-dashboard/dist/js/dx-dashboard.min.js"
        ],
        "minify": {
            "enabled": false
        },
        "sourceMap": false
    }
]

Handle the OnBeforeRender event and call the Globalize.locale() method to apply culture settings.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <title>Dashboard Web Application</title>
    <link href="css/site.min.css" rel="stylesheet" />
    <script type="text/javascript">
        function onBeforeRender(dashboardControl) {
            Globalize.locale('es');                
    }
    </script>
</head>
<body>
    <div style="position: absolute; left: 0; top: 0; right: 0; bottom: 0;">
    @(Html.DevExpress().Dashboard("dashboardControl1")
        .Width("100%")
        .Height("100%")
        .OnBeforeRender("onBeforeRender")
    )
    </div>
    <script src="js/site.min.js"></script>
</body>
</html>

Identify Non-Translated Strings

Use our UI Localization Client tool shipped as part of your DevExpress subscription. This tool streamlines the entire localization process. You can quickly find non-translated strings and translate them during a debug session.
Handle the XtraLocalizer.QueryLocalizedStringNonTranslated event to collect non-localized resource strings for further translation. The event allows you to focus on strings that require translation in your application.

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Localize UI

Satellite Resource Assemblies

Add Predefined Satellite Assemblies

Add Satellite Assemblies for Other Cultures

Configure Localization Middleware

UI Localization Client

Troubleshooting

Localize Dates, Numbers, and Currencies

Intl

Globalize

Identify Non-Translated Strings