Localizing WinForms Controls with Satellite Resource Assemblies

• Jul 02, 2024
• 5 minutes to read

When it comes to localizing .NET applications, the most common method is to use pre-built satellite resource assemblies. These assemblies contain translated resources that allow you to quickly and easily develop multilingual applications. Read the following topic in MSDN for information: Walkthrough - Localizing Windows Forms.

Note

DevExpress UI controls support two methods of localization: Satellite Resource Assemblies and Localization-Related API (Custom Localizers). There are several UI controls that can only be localized with satellite resource assemblies (for example, the Search dialog in XtraReports).

Download Satellite Assemblies

DevExpress includes satellite assemblies for a variety of languages and cultures. In most cases, you do not need to translate all language-specific resources. The DevExpress Unified Component Installer includes resource assemblies for certain languages (German (DE), Spanish (ES), Japanese (JA)). These resources are not automatically installed. You can install them at your discretion.

Navigate to the DevExpress Localization Service to download community-sourced translations for other languages. Localized resources may be incomplete. The Localization Service allows you to modify existing translations, compile, and download satellite assemblies.

Read the following topic or watch our video tutorial for information on how to prepare and download resource assemblies: Localization Service.

Watch Video: Getting Started

Note

The major version of satellite assemblies (for instance, v24.1) should match the major version of DevExpress libraries in your Windows Forms project.

Add Satellite Assemblies to Your Application

Copy the folder(s) with satellite assemblies to the application’s EXE file directory. For example, to include German assemblies, copy the folder named de from the \Bin\Framework directory to the directory of your application’s EXE file (usually the bin\Debug subdirectory). You can change the Output path to select another location.

Note

Satellite assemblies must be placed in a folder that matches the name of the culture the assemblies target. For example, if satellite assemblies target a neutral German (“de”) culture, you should place them in the “de” folder (rather than “de-DE” or some other folder).

The following diagram illustrates where to place satellite assemblies within your app directory:

Deploy the application along with satellite assemblies to an end-user’s machine. When launched, the program automatically determines the operating system’s culture, loads corresponding resource assemblies, and translates the UI.

The following images demonstrate Print Preview and Report Designer forms localized into German:

Apply Satellite Assemblies at Design Time

Install and register satellite assemblies in the global assembly cache (GAC) to change the language of DevExpress UI components in the Visual Studio designer:

• Use the Gacutil.exe tool to install and register satellite assemblies in the (GAC).
• Restart Visual Studio.

Read the following topic for instructions: How to: Install an assembly into the global assembly cache.

Note

If there are different resource assemblies with the same name (one located near the application EXE file and another installed into the GAC), the assembly installed into the GAC has a higher priority.

Specify UI Culture

Set the CurrentThread.CurrentUICulture and CurrentThread.CurrentCulture properties to the abbreviation of the required culture to specify the culture for an application (regardless of the target operating system).

Note

Although you can use a culture-independent convention for the CurrentUICulture property (for example, “de”), the CurrentCulture property must be set to a specific culture (for example, “de-DE”).

The following example demonstrates how to apply German regional settings for an application. You should execute this code before application startup.

C#

using System.Globalization;
using System.Threading;
// ...

static void Main() {
    // The following code must be executed before application startup.
    CultureInfo culture = CultureInfo.CreateSpecificCulture("de-DE");
    Thread.CurrentThread.CurrentUICulture = culture;
    Thread.CurrentThread.CurrentCulture = culture;

    // Sets the German culture as the default culture for all threads in the application. 
    CultureInfo.DefaultThreadCurrentCulture = culture;
    CultureInfo.DefaultThreadCurrentUICulture = culture;

    Application.Run(new Form1());
}

VB.NET

Imports System.Globalization
Imports System.Threading
' ...

Shared Sub Main()
    ' The following code must be executed before application startup.
    Dim Culture = CultureInfo.CreateSpecificCulture("de-DE")
    Thread.CurrentThread.CurrentUICulture = Culture
    Thread.CurrentThread.CurrentCulture = Culture

    ' Sets the German culture as the default culture for all threads in the application.
    CultureInfo.DefaultThreadCurrentCulture = Culture
    CultureInfo.DefaultThreadCurrentUICulture = Culture

    Application.Run(New Form1())
End Sub

Important

Resources are not automatically applied if the application culture changes at runtime. You need to restart the WinForms application.

Localization of Single-File Applications

If you publish a WinForms project as a single-file application (see Single-file deployment), you need to use the solution described in the Store Localized Resources in a Version Control System topic to localize your application. Otherwise, your single-file application will not be able to resolve satellite assemblies (even if you put them in correct subdirectories after you publish the application).

Troubleshooting

My Application is not Localized

Place satellite resource assemblies in the appropriate folder(s) so that the Common Language Runtime (CLR) can find them. Sometimes an application cannot find satellite assemblies. Use the standard .NET utility (Fuslogvw.exe) to find out where the CLR looks for assemblies. Read the following topics in MSDN for information:

• Assembly Binding Log Viewer (Fuslogvw.exe)
• Satellite Assembly Loading Algorithm

Certain Items in my Application are not Localized

This may occur because satellite assemblies for a certain culture are incomplete. Use the DevExpress Localization Service to translate missing resources.

Read the following topic for information: Localization Service.

My Security Permissions Prohibit Running the Application

SecurityPermission must be set to ControlThread to change the culture of Thread.CurrentThread. We do not recommend that you manipulate threads because of the security state associated with threads. Permission should only be given to trustworthy code when necessary. The application cannot change the thread culture in semi-trusted code.

Read the following topic for information: CultureInfo.CurrentCulture.