Localization and Globalization for Blazor Server
- 4 minutes to read
Follow the steps below to localize a Dashboard component into different languages and cultures in a Blazor Server Application.
Localization
Localization is a process of translating UI element captions to another language: dialog boxes, buttons, menu items, error messages, and so on.
Add Satellite Assemblies
Predefined Satellite Assemblies
DevExpress components contain predefined satellite resource assemblies for the following localizations:
- German (de)
- Spanish (es)
- Japanese (ja)
- Russian (ru)
Follow the steps below to add the localization resources to your application:
- 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.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):
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, v21.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. In this example, create thebin\Debug\netX.X\frfolder to translate your application into French.Unpack the archive with resources generated by the DevExpress Localization Service and copy all the *.v21.2.resources.dll files to the newly created subdirectory.
Register a Dashboard Localization Service
Register the DashboardLocalizationProvider as a singleton service:
public void ConfigureServices(IServiceCollection services) {
// ...
services.AddSingleton<IDashboardLocalizationProvider, DashboardLocalizationProvider>();
// ...
}
Configure Localization Middleware
Blazor Server apps are localized using Localization Middleware. 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.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
var supportedUICultures = new[] { "en-US", "de-DE" };
var localizationOptions = new RequestLocalizationOptions()
.SetDefaultCulture(supportedCultures[1])
.AddSupportedUICultures(supportedUICultures);
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. Pass the string identifier and its values as the method’s parameter:
<head>
<script>
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" });
}
</script>
</head>
Globalization
Globalization is a process of formatting dates, numbers, and currencies according culture-specific assumptions.
Blazor Server apps are globalized using Localization Middleware. 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.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
var supportedCultures = new[] { "en-US", "de-DE" };
var localizationOptions = new RequestLocalizationOptions()
.SetDefaultCulture(supportedCultures[1])
.AddSupportedCultures(supportedCultures)
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:
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:
<head>
<script>
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);
}
}
</script>
</head>