Localization

  • 4 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.

Blazor-Localization-Overview

The localization mechanism depends on your application’s hosting model:

Blazor Server

DevExpress components in server-side Blazor applications use the standard localization mechanism from the .NET framework - Satellite Resource Assemblies (libraries that contain translated resources). For more information, refer to the Creating Satellite Assemblies MSDN article.

Predefined Satellite Assemblies

DevExpress components provide 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.

  1. Create and configure the application as described in the Create a New Blazor Application document.
  2. In Visual Studio, select Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.
  3. In the invoked dialog, select the DevExpress package source. Find the DevExpress.Blazor.XX NuGet package with the required culture and install it.

    Blazor-localization-NuGet-Packages

Satellite Assemblies for Other Cultures

To download satellite assemblies for DevExpress Blazor components that correspond to other cultures, use the DevExpress Localization Service. This service allows you to create a custom set of satellite assemblies, modify resources, and download assemblies.

Ensure that the major version of the satellite assemblies (for instance, v19.2) matches the major version of DevExpress Blazor package in the project. For more information on how to prepare and download resource assemblies, watch DevExpress Localization Service - Getting Started.

Blazor-Localization-Service

Follow the steps below to add downloaded assemblies to your Blazor application.

  1. Create a subdirectory in the application's EXE file directory (usually the bin\Debug\netcoreappX.X\ subdirectory) with the name that corresponds to the generated resources' culture (for example, bin\Debug\netcoreappX.X\fr to translate your application into French).
  2. Unpack an archive with resources generated by the DevExpress Localization Service and copy the DevExpress.Blazor.resources.dll file to the created subdirectory.
  3. Rebuild the application.

Change a Culture

After you added satellite assemblies to your application, all Blazor components use resources that correspond to the current culture. To change the current culture in code, use the Localization approach recommended by Microsoft as demonstrated in our How to localize DevExpress Blazor components example.

var cultureName = culture.Name;
var uri = new Uri(NavigationManager.Uri)
    .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
var query = $"?culture={Uri.EscapeDataString(cultureName)}&" +
            $"redirectUri={Uri.EscapeDataString(uri)}";

NavigationManager.NavigateTo("/Culture/SetCulture" + query, forceLoad: true);

Blazor WebAssembly

DevExpress components in Blazor WebAssembly applications are localized using the IDxLocalizationService interface implementation. Follow the steps below to enable localization in WebAssembly applications.

  1. Download needed satellite assemblies using the DevExpress Localization Service.

    Ensure that the major version of the satellite assemblies (for instance, v19.2) matches the major version of the DevExpress Blazor package in the project. For more information on how to prepare and download resource assemblies, watch DevExpress Localization Service - Getting Started.

    Blazor-Localization-Service

  2. Convert downloaded resource files (\src\DevExpress.Blazor\Resources\*.resx) to dictionaries (for example, using T4 text templates).

    public static class LocalizationProvider {
        [ThreadStatic]
        static readonly Dictionary<string, Dictionary<string, string>> localizations = new Dictionary<string, Dictionary<string, string>>{
            {"de", new Dictionary<string, string> {
                {"DxBlazorStringId.Calendar_TodayButton", "Heute"},
                {"DxBlazorStringId.Calendar_ClearButton", "Entfernen"},
                {"DxBlazorStringId.DateEdit_ChooseDate", "Ein Datum auswählen"},
                ...
                {"DxBlazorStringId.PivotGrid_TotalFormat", "{0} Gesamt"},
            }},
            {"ja", new Dictionary<string, string> {
                {"DxBlazorStringId.Calendar_TodayButton", "今日"},
                {"DxBlazorStringId.Calendar_ClearButton", "クリア"},
                {"DxBlazorStringId.DateEdit_ChooseDate", "日付を選択する"},
                ...
                {"DxBlazorStringId.PivotGrid_TotalFormat", "{0} 合計"},
            }},
        };
        public static string GetString(string culture, string key) {
            Dictionary<string, string> localization;
            string value = null;
            if(localizations.TryGetValue(culture, out localization)) {
                localization.TryGetValue(key, out value);
            }
            return value;
        }
    }
    
  3. Use the IDxLocalizationService.GetString(key) method to get a translated string that corresponds to a specific UI element from the dictionary. For a complete list of string identifiers that define Blazor component UI elements, refer to DxBlazorStringId.

    string IDxLocalizationService.GetString(string key) {
        var culture = CultureInfo.CurrentUICulture.Name;
        if(customLocalizations.TryGetValue(culture, out var localization)) {
            if(localization.TryGetValue(key, out var value)) 
                return value;
        }
        return LocalizationProvider.GetString(culture, key) ?? base.GetString(key);
    }
    
    NOTE

    Example: A complete sample project is available at How to localize DevExpress Blazor components.