Localization

• Apr 11, 2024
• 5 minutes to read

DevExpress Blazor components ship with localizable resources for UI elements, such as editor labels, buttons, menu items, error messages, and dialog boxes. Our components use English as the default language. This topic describes how to localize DevExpress components for other languages.

View Example: How to localize DevExpress Blazor components

Predefined Satellite Assemblies

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

• German
• Spanish
• Japanese

You can find localization packages in the Dependencies section of your Solution Explorer:

Follow the steps below to add these assemblies to your project:

1. In Visual Studio, select Tools → NuGet Package Manager → Manage NuGet Packages for Solution.
2. In the invoked dialog, select the DevExpress package source.

3. Find the DevExpress.Blazor.XX NuGet package with the required culture and install it:

   

4. Optional. Find the DevExpress.Blazor.RichEdit.XX NuGet package with the required culture and install it to localize the Rich Text Editor.
5. Change the application’s culture. Use one of the techniques described in the Microsoft documentation: ASP.NET Core Blazor globalization and localization.
6. Rebuild the application.

Satellite Assemblies for Other Cultures

In Blazor applications, DevExpress components use the standard localization mechanism from the .NET framework – Satellite Resource Assemblies (libraries that contain translated resources). Refer to the following MSDN article for more information: Create Satellite Assemblies for .NET Apps.

Use the DevExpress Localization Service to create and download a custom set of satellite assemblies, and modify resources.

Ensure that the major version of the satellite assemblies (for instance, v23.2) matches the major version of the DevExpress Blazor package in the project.

For more information on how to prepare and download resource assemblies, refer to the following video: DevExpress Localization: Getting Started.

To apply satellite assemblies for DevExpress Blazor components for other cultures, use an approach that corresponds to your application’s hosting model.

Blazor Server

Follow the steps below to add downloaded assemblies to your Blazor Server application:

1. Create a subdirectory in the application’s EXE file directory (usually in the bin\Debug\netX.X\ folder) with a name that corresponds to the resource’s culture (for example, bin\Debug\net6.0\it - to translate your application into Italian).
2. Unpack the archive with resources generated by the DevExpress Localization Service and copy the DevExpress.Blazor.v23.2.resources.dll file to the newly created subdirectory.
3. Optional. To localize the Rich Text Editor, copy the DevExpress.Blazor.RichEdit.v23.2.resources.dll file to the same subdirectory.
4. Change the application’s culture. Use one of the techniques described in the Microsoft documentation: ASP.NET Core Blazor globalization and localization.
5. Rebuild the application.

Blazor WebAssembly

Follow the steps below to add downloaded assemblies to your Blazor WebAssembly application:

1. Enable the BlazorWebAssemblyLoadAllGlobalizationData property in the project file:

     <PropertyGroup>
     ...
       <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
     </PropertyGroup>
   

2. Install the Microsoft.Extensions.Localization NuGet package.

3. Create the Resources folder in your Blazor project and copy the LocalizationRes.resx and LocalizationRes.<culture_name>.resx files from the DevExpressLocalizedResources_2023.2_<culture_name>\src\DevExpress.Blazor\Resources folder to this new folder.

4. Optional. Follow these steps to localize the Rich Text Editor:

   1. Open the DevExpressLocalizedResources_2023.2_<culture_name>\src\DevExpress.Blazor.RichEdit\Resources folder.
   2. In this folder, add the RichEdit prefix to the names of the LocalizationRes.resx and LocalizationRes.<culture_name>.resx files.
   3. Copy the RichEditLocalizationRes.resx and RichEditLocalizationRes.<culture_name>.resx files to your project’s Resources folder.

5. Make sure that the following files exist in your Blazor project’s Resources folder:

   • The LocalizationRes.Designer.cs file.
   • The RichEditLocalizationRes.Designer.cs file, if you followed the previous optional step.

   In case the LocalizationRes.Designer.cs (RichEditLocalizationRes.Designer.cs) file is not present, open the LocalizationRes.resx (RichEditLocalizationRes.resx) file and set its Access Modifier property to Public.

   

6. Create a localization service. Depending on whether you need to localize the Rich Text Editor component, obtain the localization service’s code from the following Common Approach or DxRichEdit Approach tab:

   Common Approach

   using System.Globalization;
   using DevExpress.Blazor.Localization;
   
   namespace BlazorWebAssembly.Services {
       public class LocalizationService : DxLocalizationService, IDxLocalizationService {
           string? IDxLocalizationService.GetString(string key) {
               return CultureInfo.CurrentUICulture.Name == "it-IT" ?
                   Resources.LocalizationRes.ResourceManager.GetString(key) :
                   base.GetString(key);
           }
       }
   }
   

   DxRichEdit Approach

   using System.Globalization;
   using DevExpress.Blazor.Localization;
   
   namespace BlazorWebAssembly.Services {
       public class LocalizationService : DxLocalizationService, IDxLocalizationService {
   
           string? IDxLocalizationService.GetString(string key) {
               return CultureInfo.CurrentUICulture.Name == "it-IT" ?
                   GetLocalizationString(key) :
                   base.GetString(key);
           }
   
           string? GetLocalizationString(string key) {
               string? res = DxBlazorApplication1.Resources.LocalizationRes.ResourceManager.GetString(key);
               return res ?? DxBlazorApplication1.Resources.RichEditLocalizationRes.ResourceManager.GetString(key);
           }
       }
   }
   

7. Register the localization service in the Program.cs file:

   using System.Globalization;
   // ...
   using DevExpress.Blazor.Localization;
   using BlazorWebAssembly.Services;
   // ...
   builder.Services.AddSingleton(typeof(IDxLocalizationService), typeof(LocalizationService));
   

8. Change the application’s culture. Use one of the techniques described in the Microsoft documentation: ASP.NET Core Blazor globalization and localization.

9. Rebuild the application.

Identification of Non-Translated Resources

• Use our DevExpress UI Localization Client tool to identify untranslated strings of DevExpress UI controls and translate them during a debug session. The utility automatically generates RESX files with translated resources and adds them to the project. Note that the tool is not available in WebAssembly projects.

• Handle the XtraLocalizer.QueryLocalizedStringNonTranslated event to collect non-localized resource strings for translation.

Use XtraLocalizer to Localize DevExpress Controls at Runtime

The global XtraLocalizer class implements a localization-related API that allows you to translate DevExpress UI controls and forms into different languages without the need to use satellite assemblies.

To localize UI elements in your Blazor application, assign a handler to the QueryLocalizedString event. Use event argument properties to determine the processed string and specify a new value.

Since Blazor applications support multi-threaded rendering, call the HandleAllThreadEvents() method to forward information about localization-related events to all threads in the application.

@using DevExpress.Utils.Localization.Internal;
@using DevExpress.Utils.Localization;

protected override async Task OnInitializedAsync() {
    XtraLocalizer.HandleAllThreadEvents();
    XtraLocalizer.QueryLocalizedString += 
    new EventHandler<XtraLocalizer.QueryLocalizedStringEventArgs>(XtraLocalizer_QueryLocalizedString);
}
static private void XtraLocalizer_QueryLocalizedString(object sender, XtraLocalizer.QueryLocalizedStringEventArgs e) {
    if (e.StringIDType == typeof(DxBlazorStringId)) {
        if ((DxBlazorStringId)e.StringID == DxBlazorStringId.A11y_Grid_SearchBox)
            e.Value = "Enter text to search grid data. Use space to separate several search strings";
        if ((DxBlazorStringId)e.StringID == DxBlazorStringId.Grid_SearchBoxNullText)
            e.Value = "Search...";
    }
}