Localizing WinForms Controls via Satellite Resource Assemblies
- 7 minutes to read
This document demonstrates the most common approach to localizing a .NET application using Satellite Resource Assemblies (libraries that contain translated resources). These assemblies are the standard localization mechanism provided by the .NET Framework, to build multi-language applications. Refer to the Localizing Applications topic in MSDN to learn more about localization.
Note
Important: You can also localize applications using custom localizers, but some controls contain form resources (e.g., the XtraReports Search dialog), which must be translated via satellite assemblies. Thus, localization via resources is recommended.
This document consists of the following sections.
- Obtaining Satellite Assemblies
- Choosing Cultures to Localize
- Adding Satellite Assemblies to Your Application
- Selecting a Culture Different from the System Culture
- Troubleshooting
Obtaining Satellite Assemblies
In most cases, it is not necessary to manually translate all language-specific resources, because DevExpress ships with satellite assemblies for a variety of languages and cultures.
The .NET Products Installer provides resource assemblies for many popular languages. It registers these assemblies into the GAC (Global Assembly Cache) of your development machine, and also places them in the installation folder (“C:\Program Files (x86)\DevExpress 17.2\Components\Bin\Framework\“, by default).
This folder contains a subfolder with translated libraries. Each subfolder is named by its common culture abbreviation:
- de - German;
- es - Spanish;
- ja - Japanese;
- ru - Russian.
Note
For a full list of available culture names, refer to the Language Identifier Constants and Strings topic in MSDN.
If these folders do not contain assemblies for the language you require, or you wish to provide custom translations for specific UI elements, you can use the DevExpress Localization Service. This service allows you to download and modify the satellite assemblies required to localize applications created with DevExpress .NET controls.
For more information on preparing and downloading resource assemblies, refer to the Localization Service documentation, or watch the training video on YouTube.
Choosing Cultures to Localize
There are three ways to localize an application.
Localize an application for a single culture.
Copy the required satellite assemblies to the directory where the application’s EXE file is located. After it is deployed on an end-user’s machine, the program will automatically determine the operating system’s culture.
Unpack the downloaded archive, locate the folder by its abbreviated culture name (e.g., de for the German culture) and copy it to the application’s EXE file directory.
Note
No code has to be written in this case, and you can omit the remaining steps of this tutorial.
Localize an application for numerous cultures, based on the locale of the operating system.
This is the most common approach to localization. It is similar to the one described above, with one exception: multiple folders are created within the application’s directory, each containing satellite assemblies for a single culture. The program will automatically determine the operating system’s culture, and load the appropriate assemblies, so it is not necessary to write additional code.
Localize an application for a specific culture, regardless of the locale of the operating system.
See the Select a Culture Different from the System Culture article for details on how to achieve this.
Adding Satellite Assemblies to Your Application
To add localized resources to your application, copy satellite assemblies from the unpacked archive to the corresponding subfolders of your application’s directory. The subfolder’s name is the culture’s abbreviation.
For example, to include German assemblies, copy the folder named de from the \Bin\Framework\ directory to the directory where your application’s EXE file is located; most commonly, it is the bin\Debug\ subdirectory of an application. You can, however, select another location by changing your project’s Output path defined in its general settings, as shown in the following image.
The following diagram illustrates where satellite assemblies should be placed within your application’s directory.
Note
Instead of copying satellite assemblies into the application’s folder, it is also possible to install them to the GAC. Note that if there are different resource assemblies with the same name - one located near the application EXE file and another installed in the GAC - the assembly from the GAC will have a higher priority.
After the application is deployed on an end-user’s machine, the program will automatically determine the operating system’s culture.
The following images demonstrate Print Preview and Report Designer forms localized into German. It is possible to localize all DevExpress components in a similar manner.
Selecting a Culture Different from the System Culture
Assign the required culture’s abbreviation to the CurrentThread.CurrentUICulture and CurrentThread.CurrentCulture properties to manually specify the culture for an application (regardless of the target operating system).
Note that while you can use a short culture abbreviation (a neutral culture) for the CurrentUICulture property (e.g., “de”), the CurrentCulture property needs to be set a specific culture (e.g., “de-DE”).
The following sample code sets German regional settings for an application.
using System.Globalization;
using System.Threading;
// ...
static void Main() {
// Create a new object, representing the German culture.
CultureInfo culture = CultureInfo.CreateSpecificCulture("de-DE");
// The following line provides localization for the application's user interface.
Thread.CurrentThread.CurrentUICulture = culture;
// The following line provides localization for data formats.
Thread.CurrentThread.CurrentCulture = culture;
// Set this culture as the default culture for all threads in this application.
// Note: The following properties are supported in the .NET Framework 4.5+
CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;
// Note that the above code should be added BEFORE calling the Run() method.
Application.Run(new Form1());
}
Note
If you intend to allow end-users to select from multiple predefined cultures, execute this code before the form is loaded. Although it is possible to assign the CurrentCulture and CurrentUICulture properties on the fly, there is no common method to reload all resources.
Troubleshooting
My application is not localized.
To use satellite resource assemblies, place them in the appropriate locations, so that they can easily be found by the Common Language Runtime (CLR). In some cases, the application may not be able to locate the satellite assemblies. If this is the case, you can check to see where it looks for assemblies using the standard .NET Fuslogvw.exe utility. Refer to the Assembly Binding Log Viewer (Fuslogvw.exe) topic in MSDN for more information.
Some items in my application are not localized.
This may occur because satellite assemblies for a particular culture are not complete. You can translate the missing strings via the DevExpress Localization Service. Refer to the Localization Service documentation to learn more.
My security permissions prohibit running the application.
SecurityPermission must be set to ControlThread to change the culture of Thread.CurrentThread. Note that manipulating threads, however, is dangerous, because of the security state associated with threads. Therefore, permission should only be given to trustworthy code, and only when necessary. The application cannot change the thread culture in semi-trusted code (see the CultureInfo.CurrentCulture property description in MSDN for details).