Localization and Globalization for Blazor Server

• Sep 27, 2024
• 5 minutes to read

Follow the steps below to localize a Dashboard component into different languages and cultures in a Blazor Server Application.

View Example: Dashboard for Blazor Server - Localization

Localization

Localization is a process of translating UI element captions to another language: dialog boxes, buttons, menu items, error messages, and more.

Satellite Resource Assemblies

Add Satellite Assemblies

Predefined Satellite Assemblies

DevExpress components contain predefined satellite resource assemblies for the following localizations:

• German (de)
• Spanish (es)
• Japanese (ja)

Follow the steps below to add the localization resources to your application:

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

Satellite Assemblies for Other Cultures

You can add the assemblies for other cultures to your Blazor Server application. Follow the steps below to add the resources for the French market (the fr culture):

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

   Modules to translate:

   • Dashboard.Core
   • Dashboard.Web
   • DataAccess
   • Web.Resources

2. 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. In this example, create the bin\Debug\netX.X\fr folder to translate your application into French.

3. Unpack the archive with resources generated by the DevExpress Localization Service and copy all the *.v24.2.resources.dll files to the newly created subdirectory.

Register a Dashboard Localization Service

In the Program.cs file, register the DashboardLocalizationProvider as a singleton service:

builder.Services.AddSingleton<IDashboardLocalizationProvider, DashboardLocalizationProvider>();

Configure Localization Middleware

Blazor Server apps are localized using Localization Middleware. In the Program.cs file, call the UseRequestLocalization method with the following options to configure the Localization Middleware:

AddSupportedUICultures

Adds the set of the supported UI cultures by the application.

SetDefaultCulture

Sets the default culture which is used by the application.

var supportedCultures = new[] { "en-US", "de-DE" };
var supportedUICultures = new[] { "en-US", "de-DE" };
var localizationOptions = new RequestLocalizationOptions()
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedUICultures)
    .SetDefaultCulture(supportedCultures[0]);

app.UseRequestLocalization(localizationOptions);

Localize the Specified String at Runtime

You can also localize the specified string at runtime. Handle the DashboardControlOptions.onInitializing event and call the ResourceManager.setLocalizationMessages static method. In the view, pass the string identifier and its values as the method’s parameter:

window.dashboardEvents = {
    onInitializing: (args) => {
        // Localize the specified string at runtime (the "Export To" button's caption in the dashboard title):
        DevExpress.Dashboard.ResourceManager.setLocalizationMessages({ "DashboardStringId.ActionExportTo": "Custom Text for Export Button" });
    }
}

See the following topic for more information about how to apply JavaScript customization to a Dashboard component in Blazor: JavaScript Customization of Dashboard Component.

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.

To use UI Localization Client in your Blazor Server application, register the DashboardLocalizationProvider as a singleton service in Program.cs:

builder.Services.AddSingleton<IDashboardLocalizationProvider, DashboardLocalizationProvider>();

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

Globalization

Globalization is a process of formatting dates, numbers, and currencies according culture-specific assumptions.

Blazor Server apps are globalized using Localization Middleware. In the Program.cs file, call the UseRequestLocalization method with the following options to configure the Localization Middleware:

AddSupportedCultures

Adds the set of the supported cultures by the application.

SetDefaultCulture

Sets the default culture which is used by the application.

var supportedCultures = new[] { "en-US", "de-DE" };
var supportedUICultures = new[] { "en-US", "de-DE" };
var localizationOptions = new RequestLocalizationOptions()
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedUICultures)
    .SetDefaultCulture(supportedCultures[0]);

app.UseRequestLocalization(localizationOptions);

You can implement a UI that allows users to change the culture at runtime. The following example shows how to save the current culture in a cookie that can be read by the Dashboard Localization Provider:

View Example

More information: Dynamically set the culture by user preference.

Apply Custom Formatting for Numbers and Dates

You can use Globalize to apply custom formatting for Numbers and Dates. Handle the DashboardControlOptions.onInitializing event and specify the formatting:

window.dashboardEvents = {
    onInitializing: (args) => {
        // Apply custom formatting for numbers and dates:
        var json = { main: {} };

        json["main"]["de"] = {
            numbers: { "currencyFormats-numberSystem-latn": { standard: "C #,##0.00 ¤" } },
            dates: { calendars: { gregorian: { dateTimeFormats: { availableFormats: { yMd: "dd MMM y" } } } } }
        };
        Globalize.load(json);
    }
}

See the following topic for more information about how to apply JavaScript customization to a Dashboard component in Blazor: JavaScript Customization of Dashboard Component.