Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Collapse]Build an Application
  [Expand]Choose Application UI
   Data Management Controls
  [Expand]Printing and Exporting
  [Expand]WinForms MVVM
  [Expand]Skins
  [Collapse]Localization
    Localizing WinForms Controls via Satellite Resource Assemblies
    Localizing WinForms Controls via Localizer Objects
  [Expand]Right-to-Left Layout
   Redistribution and Deployment
 [Expand]Controls and Libraries
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Localizing WinForms Controls via Satellite Resource Assemblies

This document demonstrates the most common approach to localizing a .NET application using Satellite Resource Assemblies (libraries that contain translated resources). This is the standard localization mechanism provided by the .NET Framework, appropriate for world-ready multi-language applications. To learn more about localization, refer to the Localizing Applications topic in MSDN.

Note

Important: You can also localize your applications using custom localizers, but some controls contain form resources (e.g., the XtraReports Search dialog), and the only way to translate them is to create satellite assemblies. Thus, localization via resources is the preferable solution.

This document consists of the following sections.

Expanded Obtaining Satellite Assemblies

In most cases, you do not need to manually translate all language-specific resources, because DevExpress already delivers satellite assemblies for a large variety of languages and cultures.

Resource assemblies for some popular languages are provided by the .NET Products Installer. 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.1\Components\Bin\Framework\", by default).

This folder contains a subfolder with translated libraries. Each subfolder is named according to common culture abbreviations:

  • de - German;
  • es - Spanish;
  • ja - Japanese;
  • ru - Russian.
Note

For a full list of available culture names, refer to the National Language Support (NLS) API Reference 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.

Expanded Choosing Cultures to Localize

It is now possible to localize an application in three different ways.

  1. Localize an application for a single culture.
    To do this, copy the required satellite assemblies into your application's directory, where its EXE file is located. After the application is deployed on an end-user's machine, the program will automatically determine the operating system's culture info.

    Unpack the downloaded archive, locate a folder named according to the abbreviation of the required culture (e.g., de for the German culture) and simply copy it into the directory where the EXE file of your application is located.

    Note

    No code has to be written in this case, and you can omit the following steps of this tutorial.

  2. Localize an application for numerous cultures, based on the locale of the operating system under which it is running.
    This is the most common approach to localization. It is similar to the one above, with one exception: multiple folders are created within your application's directory, each containing satellite assemblies for a single culture. Again, no code needs to be written, since the program will automatically determine the operating system's culture info, and load the appropriate assemblies for this culture.

  3. Localize an application for a specific culture, regardless of the operating system under which it is running.
    The following section provides details on how to achieve this: Select a Culture Different from the System Culture.

Expanded 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 your application's folder, it is also possible to install them into 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 info.

The following images demonstrate Print Preview and Report Designer forms localized into German. It is possible to localize all DevExpress components in the same way.

Expanded Selecting a Culture Different from the System Culture

To manually specify a culture for your application (regardless of the operating system under which the application will be run), you need to assign the required culture's abbreviation to the CurrentThread.CurrentUICulture and CurrentThread.CurrentCulture properties.

Note that while the CurrentUICulture property can use a short culture abbreviation (in this case, a neutral culture for this locale will be used, e.g., "de"), the CurrentCulture property requires the full string parameter to define a specific culture (e.g., "de-DE").

The following sample code sets German regional settings for an application.

Note

If you intend to allow end-users to select cultures from multiple predefined cultures, it is recommended that you execute this code before your 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.

Expanded 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). This is because your satellite assemblies will all have the same name as your application's assemblies. In some cases, your application may not be able to locate the satellite assemblies. If this is the case, you can check to see where your application looks for assemblies using the standard .NET Fuslogvw.exe utility. For more information on this, refer to the Assembly Binding Log Viewer (Fuslogvw.exe) topic in MSDN.


Some items in my application are not localized.
This may occur because the satellite assemblies for this particular culture are not complete. You are welcome to translate the missing strings using the DevExpress Localization Service. To learn more, refer to the Localization Service documentation.


My security permissions prohibit running the application.
Changing the culture of Thread.CurrentThread requires a SecurityPermission with the ControlThread value set. Manipulating threads is dangerous, because of the security state associated with threads. Therefore, this permission should only be given to trustworthy code, and only when necessary. Your application cannot change the thread culture in semi-trusted code (for details see the CultureInfo.CurrentCulture property description in MSDN).

How would you rate this topic?​​​​​​​