Document home

Visual C++

Windows Forms Localization and Internationalization

Windows Forms (Wikipedia) is the classic framwork to build GUI application in .NET. The more recent framework is WPF. Windows Forms uses primary .resx files to store resource data. Soluling localization tool and service support Windows Forms.

The following chapters describe Windows Forms localization step by step.

Localization Process

You can localize Windows Forms applications using the following methods:

1. Visual Studio project or solution file localization method

The first way to localize a .NET project is to add a Visual Studio project file (.csproj or .vbproj) into a Soluling project. Soluling reads the project file to locate all the resource files it uses (.resx, .xaml, images, etc.). You don't have to select all the resources files manually, but adding one single project file is enough.

If you have multiple project files, you can add a Visual Studio solution file (.sln) instead of individual project files. If you later add new projects into your solution, you don't have to add anything into your Soluling project because Soluling will automatically find the new items from the solution file and adds them to the project. The result you will get by using a Visual Studio solution file instead of individual project files is exactly the same. Your Soluling project will contain the same sources, you can configure them in the same way, and the output files will be the same. Support for Visual Studio solution file is to make things easier for you.

2. Assembly file localization method

Another way to localize a .NET project is to add an assembly file into a Soluling project. Soluling reads the assembly to locate all the resource data it uses. When building, Soluling creates satellite assembly files. There is one output file (.resources.dll) for each language. You don't need to have the source code files. The only file you need is the original assembly file.

In addition to creating satellite assembly files, Soluling can also create localized assembly files. The difference is that the localized assembly file is an identical copy of the original assembly. It contains exactly the same code segments as the original. You can replace the original assembly with localized assembly without breaking anything. You deploy the localized assembly file without the original assembly file. The satellite assembly files, on the other hand, contain only resources. They do not contain any code. They do not run alone but must always be deployed with the original assembly file. By default, Soluling creates satellite assembly files. You can change this by using the Output sheet of Source dialog.

3. Resource file localization method

The last localization method is to localize each resource file (.resx). Soluling reads the original resource file and, when building, creates localized resource files. There is one output file for each language. Even this method seems easy, it has two drawbacks. First is that you can not use localized resource files directly, but you have to put them inside an assembly file. If you use resource file localization, it is up to you to compile either the localized assembly file(s) or localized satellite assembly file(s). Second is that a typical .NET project contains dozens of resource files, and in many cases, they are scattered around several folders. You have to add them all to your Soluling project. Even using wildcards, it may be complicated. Also, every time you add a new resource file, you may have to add it to the project.

If you use this method you can make Visual Studio to automatically compile your satellite assembly files.

Creating a Soluling project

 

Scan Rules

Soluling uses scan rules to specify what components and properties are localized and how they are localized. Form resources are the most important resource type of Windows Forms applications. You use Visual Studio to create and edit forms. Each form is stored in form files (.resx and .Design.cs/Design.vb). The .resx file uses the standard resx format to store most of the properties of the component on the form. Some of the properties are not written into .resx but they are hard coded into .Design.cs or .Design.vb files. Only data in .resx can be localized. Fortunately pretty much all properties that could need localization are stored in .resx instead of .Design.cs. In some rare cases you might want to localize a propety that is stored in .Design.cs (e,g. a color property). This cannot be done but you have to add the property value to a custom .resx and on run time read the value from .resx and assign it to the property.

String typed properties

The rules work such way that by default all string typed properties are localized and all other properties are not localized. This method picks up the following string properties:

Property Value
Text Form
label1.Text This is a sample
button1.Text &Get
folderBrowserDialog1.SelectedPath C:\MyDataFiles

All three Text propeties should be translated. However SelectedPath property should not be localized. To make this possible Windows Forms scan property rules can contain exception rules. They specify those string type properties that are not localized (remember by default all string typed properties are localized). By default the rules contains exceptions for all those Windows Forms properties that should not be localized. For example.

Component name Property name
System.Windows.Forms​.FolderBrowserDialog SelectedPath

The abovet rule excludes SelectedPath property of FolderBrowserDialog.

Note! The component name is the component type name. For example Windows Forms label control's type name is System.Windows.Forms.Label.

Font properties

 

Size and position properties

 

Binary properties

 

Other properties

It is very rare that you need to localize other kind of properties than shown above. If you do Soluling can handle it. Other property types such as enumerations and numbers are not localized unless you add them into the scan property rules.

Localizable property

In order to localize a .NET Windows Forms application each form or user control of the application has to have Localizable property set true. This makes Visual Studio to store the properties of the form in the .resx file instead to hard code them to the source code. Having the resources in the .resx file makes localization possible.

To change the Localizable property true open your project, select each form and user control, and make sure that Localizable property is set to true.

Runtime language change

This topic is for Windows Forms. If you use WPF read this.

Soluling extends the .NET framework by providing classes to performs runtime language change. It makes it possible to start an application in one language and later change the language on run time as many times as possible. Soluling's runtime language change is very fast and flicker-free.

Soluling.Forms namespace contains classes and functions that let you change the language of .NET application on run time. <data-dir>\Library\NET\Forms contains the source code of C# library project that contains the classes. If you compile this project you will have Soluling.Forms.dll library assembly file. It contains all the classes.

Soluling.Forms.Translator is a class that translates forms. Soluling.Resources ia a class works with satellite assembly files. Finally Soluling.Forms.SelectLanguage contains a dialog that show available languages and lets the use to select a new language.

Adding runtime language change is very easy. At minimum it only requires that you add one line of code into your application.

private void languageToolStripMenuItem_Click(object sender, EventArgs e)
{
  SelectLanguage.Select();
}

It is simple like that!

Form translating requires more explanation. Soluling.SelectLanguage.Select calls Soluling.Forms.Translator.SetUserInterfaceLanguage function that performs the resource loading and calls Soluling.Forms.Translator.Translate function that translates existing forms. It is very important to understand what happens here. Soluling reads the localized form data from satellite assembly file. This means that all the component and properties of the form that exist in the localized form data will be assigned. However if you changed any property value from code, for example in Load or Show events, the property values do not change. If these so called dynamic property values need to be localized you have to set them again after language change. Let's have an example.

<data-dir>\Samples\WindowsForms\LanguageChange contains a simple application using runtime language change. Form1_Load set the initial value of the label2.Content.

private void Form1_Load(object sender, EventArgs e)
{
  UpdateItems();
}

private void UpdateItems()
{
  label2.Text = Properties.Resources.String1;
}

When application has loaded the form is not the same as in design time. The design time state is the state that exist in the .resx file (e.g. form data). The Text property of the label2 control have been changed on run time. When a language change occurs Soluling automatically updates the static properties (e.g. those that exist on the form data) but does not change these dynamic properties. This is why you have to set them again. The following code changes the language and translates dynamic properties.

private void languageToolStripMenuItem_Click(object sender, EventArgs e)
{
  if (SelectLanguage.Select())
    UpdateItems();
}

SelectLanguage.Select changes the language and UpdateItems resets the dynamic properties using the new language.

Now our application works. After language change you have to remember to resets any dynamic properties. This might seem a bit complicated but in most cases your language change routine is on the main menu or on the main form. In a situation like that you only have one form existing at that moment so you only have to take care if resetting dynamic properties of that form. All the other forms that you create after language change will automatically use the new language.

Compile satellite assembly files

If you use assembly localization or Visual Studio project or solution localization method Soluling will automatically compile the satellite assemblies or localized assemblies during the build process. If you use resource file localization method you have to make Visual Studio to compile the satellite assemblies. Fortunately this is very easy. All you have to do is to add all localized .resx files into your Visual Studio project. Next time Visual Studio builds the assembly it also builds the satellite assemblies.

  1. In Visual Studio's Solution Explore click Show All Files. Now all files are show in Explorer.
  2. Underneath of each form file you can see the localized form files (if any). Right click a localized resource file and choose Include In Project. Visual Studio adds the localized resource file into the project.
  3. Repeat #2 for each resource file you have.
  4. Finally click Show All Files again to hide files that are not included.

The following image show a project that has two original resource files: Properties\Resources.resx and Form1.resx. In addition the project contains Finnish version of those resource files: Properties\Resources.fi.resx and Form1.fi.resx.

Next time you build your project Visual Studio not only build the main assembly (VisualStudioCompile.exe) but alos the Finnish satellite assembly (fi\VisualStudioCompile.resources.dll). Whenever you add new languages or new resource files remember to include the new files into the project.

Samples

GitHub and <data-dir>\Samples\WindowsForms contains following Windows Forms (.NET) samples:

Directory Description Notes
Driving Shows how to internationalize, localize and add a runtime lanugage switch for a Windows Forms application.
Original Original English driving application that has not been internationalized.
Localized Internationalized and localized driving application.
Multilingual As above but with a runtime language switch.
Try this first!
Tutorial A tutorial sample. Read <data-dir>\Library\NET\NET.pdf to complete the tutorial.
BadSample Original application. Contains lots of hard coded strings, code that is not internationalized, and user interface that requires reworking.
GoodSample Above application internationalized and localized properly.
Try this first!
     
BiDi Shows how to localize to bi-directional languages or from bi-directional languages. Contains following projects:
BiDiArabic A sample application that uses originally Arabic and right to left layout. The application is localized to English.
BiDiEnglish As above but uses originally English and left to right layout. The application is localized to Arabic.
 
Comment Shows how to add comments for the resource string.  
Custom Shows how to localize custom controls such as 3rd party or your own controls. This samples implements SampleLabel that extends the standard Label control adding a new Custom* properties. Contains following projects:
Application A sample application that uses SampleLabel control.
Control A project that implements SampleLabel control
 
Database Shows how to implement a multilingual application that uses multilingual database. Runtime language switch
Encodings Shows how to use various encodings in resx files.  
FileDialog Shows how to localize Filter property of OpenFileDialog and SaveFileDialog dialogs.  
HardCoded Shows how to localize hard coded strings without internationalizing the application.  
Ignore​Satellite​Assembly Shows how to disable loading of satellite assembly files.  
Image Shows how to localize images. Requires .NET 3.0 or higher.
Ime Shows how to localize input method editor values.  
Image​List Shows how to localize an image list.  
Inherited Shows how to localize an application containing inherited forms.  
Language​Switch Shows how to perform a runtime language switch. Runtime language switch
Links Shows how to localize various resource items.  
ListView Shows how to localize a ListView component.  
Platform​Files Shows how to localize platform files.  
Plural Show how to use plural messages. Contains following projects:
CustomPlural Uses custom plural patterns for zero and two.
MixedPlural Show various way to solve plural forms such as to ignoring the whole problem, using a home brew solution, and finally using the proper Soluling solution.
MultiPlural Uses two plural enabled variables.
SinglePlural Uses one plural enabled variable.
 
Resources Shows how to localize various embedded resource types.  
Resource​String​Location Shows how Soluling can locate the places where your application uses resource strings.  
ResxData Shows how to localize various resx resource types.  
Signed Show how to localize a signed assemblies. Contains following projects:
Unsiged An unsigned sample.
Snk A sample that has been signed with a SNK key (Key.snk)
Pfx A sample that has been signed with a PFX key (Key.pfx). Password for the key file is "password".
Delay A sample that has been delay signed with a PFX key (Key.pfx).
You can not run the application without first signing it. Sign.bat is a command line batch file that signs the assembly and the satellite assembly files.
Password for the key file is "password".
Satellite​Contract A sample where the versions of main assembly and the satellite assemblies can be different by using SatelliteContractAttribute.
 
Sport Shows how to localize a grid. Runtime language switch
Text Shows how to localize text and binary resource items.  
TreeView Shows how to localize a TreeView component.  
VisualStudio​Compile Shows how to localize only resx files and let Visual Studio to compile satellite assembly files.  

Samples.sln is a Visual Studio 2019 solution file that contains all the above samples. Samples are written in Visual Studio 2019 but the files are compatible to older Visual Studio version. Each project directory contains a Soluling project file that localizes the assembly found in the release directory of the project (i.e. bin\Release).

All samples work with .NET 2.0 or higher except Image that requires .NET 3.0 or higher.

How to configure localization

Project Wizard ask you some options when creating a new project. However Soluling lets you to configure the localization at very detailed level. Once you have create a project you can view and modify the configuration of each file of the project. Select a file, right click and choose Options.

Configuring Visual Studio project file localization

You can configure how to localize your Visual Studio project file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Configuring Visual Studio solution file localization

You can configure how to localize your Visual Studio solution file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Configuring assembly file localization

You can configure how to localize your .NET assembly file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Configuring resource file localization

You can configure how to localize your Windows Forms resource file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.