Localization
- 5 minutes to read
Localization is the process of translating an application’s resources into a different language. DevExpress Blazor components ship with localizable resources for UI elements, such as button captions, menu items, error messages, and dialog boxes.
In Blazor applications, DevExpress components use the standard localization mechanism from the .NET framework - Satellite Resource Assemblies (libraries that contain translated resources). For more information, refer to the following MSDN article: Creating Satellite Assemblies.
Predefined Satellite Assemblies
DevExpress components include NuGet packages with predefined satellite resource assemblies for the following cultures:
NuGet Package | Culture |
---|---|
DevExpress.Blazor.de | German |
DevExpress.Blazor.es | Spanish |
DevExpress.Blazor.ja | Japanese |
DevExpress.Blazor.ru | Russian |
Follow the steps below to enable localization for a culture from the table above.
- Create an application. If you use Microsoft project templates, configure the application as described in this topic: Microsoft Templates (Visual Studio).
- In Visual Studio, select Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.
In the invoked dialog, select the DevExpress package source. Find the DevExpress.Blazor.XX NuGet package with the required culture and install it.
Satellite Assemblies for Other Cultures
To download satellite assemblies for DevExpress Blazor components that correspond to other cultures, use an approach that corresponds to your application’s hosting model.
Blazor Server
Use the DevExpress Localization Service to create a custom set of satellite assemblies, modify resources, and download assemblies.
Ensure that the major version of the satellite assemblies (for instance, v20.2) matches the major version of the DevExpress Blazor package in the project. For more information on how to prepare and download resource assemblies, view the following video: DevExpress Localization: Getting Started.
Follow the steps below to add downloaded assemblies to your Blazor Server application.
- Create a subdirectory in the application’s EXE file directory (usually in the
bin\Debug\netcoreappX.X
\ subdirectory) with a name that corresponds to the newly generated resource culture (for example,bin\Debug\netcoreappX.X\fr
- to translate your application into French). - Unpack the archive with resources generated by the DevExpress Localization Service and copy the
DevExpress.Blazor.v20.2.resources.dll
file to the newly created subdirectory. - Rebuild the application.
Blazor WebAssembly
Use the DevExpress Localization Service to create a custom set of satellite assemblies, modify resources, and download assemblies.
Ensure that the major version of the satellite assemblies (for instance, v20.2) matches the major version of the DevExpress Blazor package in the project. For more information on how to prepare and download resource assemblies, view the following video: DevExpress Localization: Getting Started.
Follow the steps below to add downloaded assemblies to your Blazor WebAssembly application.
- Install the Microsoft.Extensions.Localization NuGet package.
Create the
Resources
folder in your Blazor project and register this folder in theProgram.cs
file:builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");
- Extract the downloaded resources.
- Copy the
LocalizationRes.resx
andLocalizationRes.fr.resx
files from theDevExpressLocalizedResources_2020.2_fr\src\DevExpress.Blazor\Resources
folder to your project’sResources
folder. Create a localization service.
using DevExpress.Blazor.Localization; using System; using System.Collections.Generic; using System.Globalization; using System.Linq; using System.Resources; using System.Threading.Tasks; public class DemoLocalizationService : DxLocalizationService, IDxLocalizationService { string IDxLocalizationService.GetString(string key) { var culture = CultureInfo.CurrentUICulture.Name; string value = null; switch(culture) { case "fr-FR": value = new ResourceManager("BlazorClientApp.Resources.LocalizationRes", typeof(DemoLocalizationService).Assembly).GetString(key); break; } return value ?? base.GetString(key); } }
Register this service in the
Program.cs
file:builder.Services.AddSingleton(typeof(IDxLocalizationService), typeof(DemoLocalizationService));
Enable the
BlazorWebAssemblyLoadAllGlobalizationData
property in the project file:<PropertyGroup> <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData> </PropertyGroup>
Rebuild the application.
Change a Culture
After you add localization resources to your application, all Blazor components use resources that correspond to the current culture.
For more information on Blazor globalization and localization, refer to the following Microsoft topics:
- .NET Core 3.1: Blazor globalization and localization
- .NET Core 5.0: Blazor globalization and localization
Blazor Server
To change the culture in Blazor Server applications, add a Razor expression to the Pages/_Host.cshtml
file’s <body>
:
@using System.Globalization
@using Microsoft.AspNetCore.Localization
<body>
@{
this.HttpContext.Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName,
CookieRequestCultureProvider.MakeCookieValue(
new RequestCulture(
new CultureInfo("fr-FR")
)));
}
</body>
After that, register the localization middleware in the Startup.cs
file:
public class Startup {
public void Configure(IApplicationBuilder app, IWebHostEnvironment env){
var supportedCultures = new[] { "fr-FR" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
.AddSupportedCultures(supportedCultures)
.AddSupportedUICultures(supportedCultures);
app.UseRequestLocalization(localizationOptions);
...
}
}
To implement a UI that allows users to change the culture at runtime, use the approach from the following example on GitHub: How to localize DevExpress Blazor components.
@using System.Globalization
@inject IJSRuntime JSRuntime
@inject NavigationManager Nav
<strong>Culture:</strong>
<div class="d-inline-block" style="margin-bottom:2rem">
<DxComboBox Data="@SupportedCultures.Cultures"
TextFieldName="NativeName"
@bind-Value="@Culture">
</DxComboBox>
</div>
@code {
CultureInfo Culture {
get => CultureInfo.CurrentCulture;
set {
var cultureName = value.Name;
var uri = new Uri(Nav.Uri)
.GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
var query = $"?culture={Uri.EscapeDataString(cultureName)}&" +
$"redirectUri={Uri.EscapeDataString(uri)}";
Nav.NavigateTo("/Culture/SetCulture" + query, forceLoad: true);
}
}
}
Blazor WebAssembly
To change the culture in Blazor WebAssembly applications, add the following code to the Program.Main
method:
using System.Globalization;
public class Program {
public static async Task Main(string[] args) {
CultureInfo cultureInfo = CultureInfo.CreateSpecificCulture("fr-FR");
CultureInfo.DefaultThreadCurrentUICulture = cultureInfo;
CultureInfo.DefaultThreadCurrentCulture = cultureInfo;
}
}
To get the name of the culture from the client and localize DevExpress Blazor components based on this culture, add the following code to the Program.Main
method:
using Microsoft.JSInterop;
using DevExpress.Blazor.Localization;
public class Program {
public static async Task Main(string[] args) {
var host = builder.Build();
var jsInterop = host.Services.GetRequiredService<IJSRuntime>();
var result = await jsInterop.InvokeAsync<string>("blazorCulture.get");
if(result != null) {
var culture = new CultureInfo(result);
CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;
}
}
}
To change the culture dynamically, enable the BlazorWebAssemblyLoadAllGlobalizationData
property in the project file (if you have not already done it):
<PropertyGroup>
<BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>
To implement a UI that allows users to change the culture at runtime, use the approach from the following example on GitHub: How to localize DevExpress Blazor components.
@using System.Globalization
@inject IJSRuntime JSRuntime
@inject NavigationManager Nav
<strong>Culture:</strong>
<div class="d-inline-block" style="margin-bottom:2rem">
<DxComboBox Data="@SupportedCultures.Cultures"
TextFieldName="NativeName"
@bind-Value="@Culture">
</DxComboBox>
</div>
@code {
CultureInfo Culture {
get => CultureInfo.CurrentCulture;
set {
if(CultureInfo.CurrentCulture != value) {
var js = (IJSInProcessRuntime)JSRuntime;
js.InvokeVoid("blazorCulture.set", value.Name);
Nav.NavigateTo(Nav.Uri, forceLoad: true);
}
}
}
}