Localize an XAF Application (.NET 5)

• Nov 02, 2021
• 6 minutes to read

This topic describes how to localize XAF .NET 5 applications (WinForms and ASP.NET Core Blazor).

Tip

Refer to the following topic for information on how to localize XAF .NET Framework Applications: Localize an XAF Application (.NET Framework).

Review the Application Model Basics and Localization Basics topics before proceeding.

1. Choose the language you want to use in your XAF application.

   Pre-installed languages: German (de), Spanish (es), Japanese (ja), and Russian (ru). These assemblies are available in the DevExpress Local NuGet Feed (for example, DevExpress.ExpressApp.de or DevExpress.ExpressApp.Core.All.de).

   Other languages:

   • Use the Localization Service to download satellite assemblies. See the Localize Standard XAF Modules and DevExpress Controls Used in an Application topic for more information on how to use this service to localize XAF modules.
   • Place the downloaded assemblies in the following folders:
     • In your application bin folder (for example, \Solution1.BlazorServer\bin\Debug\net5.0\fr for French). This enables runtime localization.
     • In your Model Editor’s folder (for example, C:\Program Files (x86)\DevExpress 20.2\Components\Tools\eXpressAppFrameworkNetCore\Model Editor\fr for French). This enables design-time localization.

   Satellite assemblies are reusable in any other project.

   Note

   Remember to deploy the required satellite assemblies when deploying an XAF application. Refer to the Deployment Tutorial for more details.

2. For XAF ASP.NET Core Blazor applications, add the ApplicationBuilderExtensions.UseRequestLocalization() method call. This enables the RequestLocalizationMiddleware.

   C#

    namespace MainDemo.Blazor.ServerSide { 
       public class Startup { 
           // ...
           public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { 
               // ...
               app.UseHttpsRedirection(); 
               // Enable the RequestLocalizationMiddleware 
               app.UseRequestLocalization(); 
               app.UseStaticFiles(); 
               app.UseRouting(); 
               // ...
           } 
       } 
   } 
   

   In appsettings.json, specify languages used in your application in the DevExpress:ExpressApp:Languages section. This languages list is used to:

   • Load satellite assemblies.
   • Specify the RequestLocalizationMiddleware’s RequestLocalizationOptions.SupportedCultures option.

   The first language in this list is used as the default language (specified in the RequestLocalizationOptions.DefaultRequestCulture).

   appsettings.json

   { 
       // 
       "DevExpress": { 
           "ExpressApp": { 
               "Languages": "en;de;fr" 
                // ...
           } 
       } 
   }  
   

3. In the module project, double-click the Model.DesignedDiffs.xafml file to invoke the Model Editor. Focus the root node and click Languages Manager… in the Language combo box on the Model Editor Toolbar. Add the target language in the invoked dialog and click OK. Restart Visual Studio to load localized values from the satellite assemblies and specify the application’s target language in the Language combo box.

   

   All the changes for a particular language are saved to the corresponding Model.DesignedDiffs.Localization.<language code>.xafml or Model<language code>.xafml_ file. These files resemble the Model.DesignedDiffs.xafml and Model.xafml files, which store the changes made in the Application Model in the default language (English).

   Ensure the newly created Model.DesignedDiffs.Localization.XX.xafml files are processed as embedded resources: in the Property Editor, Build Action is set to Embedded resource.

   Refer to the Localization Basics topic for more information.

4. To add a new or modify an existing translation value, use one of the tools described in the How to: Localize XAF Application Items Using XAF Tools topic.
5. To specify an application’s language, invoke the Model Editor for an application project, navigate to the Application node, and set the IModelApplication.PreferredLanguage property to a language. Refer to the Localization Basics topic for more details. If you want your application’s language to match the language on the user’s device, set the PreferredLanguage property to (User language).
6. Windows Forms Templates‘ localizable resources are not available in the Application Model by default. Refer to the How to: Localize a WinForms Template to learn how you can localize Windows Forms templates.
7. The splash screen form displayed on the Windows Forms application at startup contains a “Loading“ text label. You can specify different text as described in the Localize a Splash Form topic.
8. Start the application to ensure that all the text values are localized.

Change Language at Run Time (Blazor UI)

In UI (Runtime Language Switcher)

For the XAF ASP.NET Core Blazor UI applications, you can enable the Runtime Language Switcher. The Language Switcher is displayed in:

• The login page

  

• The settings menu

  

To enable the runtime language switcher, set the DevExpress: ExpressApp: ShowLanguageSwitcher value to True in appsettings.json:

appsettings.json

{ 
    // 
    "DevExpress": { 
        "ExpressApp": { 
            "Languages": "en;de;fr",
            "ShowLanguageSwitcher": true
        } 
    } 
}  

The Languages section must contain at least 2 supported languages to enable the runtime language switcher. These languages will be displayed in the Language switcher’s drop-down list.

The language name is retrieved from CultureInfo.NativeName.

Note

The runtime language switcher requires that IModelApplication.PreferredLanguage is set to (User language).

In Code

To change the XAF ASP.NET Core Blazor application language in code, use the IXafCultureInfoService.SetCultureAsync method.

After calling the SetCultureAsync method:

• The XafApplication is recreated in a new culture. The new culture is read from cookies in RequestLocalizationMiddleware.
• The ASP.NET Core Blazor application is reloaded even if the culture was not changed.

The code sample below demonstrates how to use IXafCultureInfoService to change the application localization.

C#

using DevExpress.ExpressApp; 
using DevExpress.ExpressApp.Actions; 
using DevExpress.ExpressApp.Blazor; 
using DevExpress.ExpressApp.Blazor.Services; 
using DevExpress.Persistent.Base; 

namespace MainDemo.Module.Blazor.Controllers { 
    public class GermanCultureController : ViewController { 
        BlazorApplication BlazorApplication => (BlazorApplication)Application; 
        IXafCultureInfoService CultureInfoService => (IXafCultureInfoService)BlazorApplication.ServiceProvider.GetService(typeof(IXafCultureInfoService)); 
        public GermanCultureController() { 
            SimpleAction myAction = new SimpleAction(this, "SetGermanCulture", PredefinedCategory.Edit); 
            myAction.Execute += async (s, e) => await CultureInfoService.SetCultureAsync("de"); 
        } 
    } 
} 

Note

In .NET 5, the libraries used for globalization functionality has been changed. Refer to the following topic for details: Globalization APIs use ICU libraries on Windows.

If a current thread’s culture is set to a culture that includes only the language and not the country (for example, “de” or “en”), the currency symbol renders as an international currency symbol (¤), for example: 100,00 ¤.

Refer to the following topics for details:

• ICU Localization - Currency symbol.
• CurrencySymbol.

Current Culture in XAF ASP.NET Core Blazor Applications

In XAF ASP.NET Core Blazor applications, the current culture is set in the following order of priority:

1. From a user’s cookies.
2. If the culture is not set in cookies, the default culture from a user’s browser is used. The Languages collection in appsettings.json should contain this culture.
3. If the Languages collection does not contain the user’s culture, the first culture from the collection is used.

When users change the current culture in the Language Switcher their cookies are updated with the new culture value.

The IModelApplication.PreferredLanguage option affects only the XAF parts of the application (Action’s captions, navigation, layout, etc.), and do not affect the application’s culture.

The application’s current culture depends on both the following settings:

• The Languages option in appsettings.json
• User’s browser preferred language, if the application supports multiple languages.

Single Language Support

If your application supports only a single language, this language should be specified in both appsettings.json and IModelApplication.PreferredLanguage:

appsettings.json

{ 
    // 
    "DevExpress": { 
        "ExpressApp": { 
            "Languages": "de" 
                // ...
        } 
    } 
}  

Localize Reports in Blazor Applications

The Reporting Module uses Reports for Blazor UI based on DevExtreme JavaScript components.

The following example demonstrates how to localize these components: Blazor Reporting - UI Customization API.