Walkthrough: Localizing Windows Forms

The Visual Studio project system provides considerable support for localizing Windows Forms applications. There are two ways to generate resource files using the Visual Studio development environment:

• Have the project system generate the resource files for localizable UI elements such as text and images on the form. The resource files are then built into satellite assemblies. These are known as forms-based resources.

• Add a resource file template and then edit the template with the XML Designer. A reason for doing the latter is to make localizable strings that appear in dialog boxes and error messages. You must then write code to access these resources. These are known as project resources.

• In general, you should use forms-based resources for all resources specific to a form in your Windows Forms application. You should use project resources for all non-forms-based user interface strings and images, such as error messages.

This walkthrough topic demonstrates both processes in a single Windows Application project.

You can also convert a text file to a resource file; for more information, see Resources in Text File Format and Resgen.exe (Resource File Generator).

To have Visual Studio generate resource files for you

1. Create a new Windows Application named "WindowsApplication1". For details, see How to: Create a New Windows Forms Application Project.

2. In the Properties window, set the form's Localizable property to true.

   The Language property is already set to (Default).

3. Drag a Button control from the Windows Forms tab of the Toolbox to the form, and set its Text property to Hello World.

4. Set the form's Language property to German (Germany).

5. Set the button's Text property to Hallo Welt.

6. Set the form's Language property to French (France).

7. Set the button's Text property to Bonjour le Monde. You can resize the button to accommodate the longer string, if necessary.

8. Save and build the solution.

9. Click the Show All Files button in Solution Explorer.

   The resource files appear underneath Form1.vb, Form1.cs, or Form1.jsl. Form1.resx is the resource file for the default culture, which will be built into the main assembly. Form1.de-DE.resx is the resource file for German as spoken in Germany. Form1.fr-FR.resx is the resource file for French as spoken in France.

   In addition, you will see files appear named Form1.de.resx and Form1.fr.resx. Visual Studio automatically creates these files in order to work around a limitation in Visual SourceSafe having to do with adding new files to a project during a save operation. The .resx files are empty and contain no resources.

10. Press the F5 key or choose Start from the Debug menu.

    You will now see a dialog box with an English, French, or German greeting depending on the UI language of your operating system.

    Note

    The UI language used in Windows is a function of the CurrentUICulture setting. If your copy of Windows has a Multilingual User Interface Pack (MUI) installed, you can change UI language in Control Panel. For more information, see the Windows Server 2003, Windows XP & Windows 2000 MUI site. If you have no MUI installed, you can change the current UI culture programmatically, as explained next.

    The following procedure shows you how to set the UI culture so the application displays your French resources. In real-world applications, you would not hard-code the UI culture in this way. The setting for the UI culture would depend instead on a user setting or an application setting.

To set the UI Culture to view specific resources

1. In the Code Editor, add the following code at the beginning of the module, before the Form1 declaration:

   ' Visual Basic
   Imports System.Globalization
   Imports System.Threading
   
   // C#
   using System.Globalization;
   using System.Threading;
   

2. Add the following code. In Visual Basic, it should go in the New function, before calling the InitializeComponent function. In Visual C#, it should go in Form1 and also before calling the InitializeComponent function.

   ' Visual Basic
   ' Sets the UI culture to French (France).
   Thread.CurrentThread.CurrentUICulture = New CultureInfo("fr-FR")
   
   // C#
   // Sets the UI culture to French (France).
   Thread.CurrentThread.CurrentUICulture = new CultureInfo("fr-FR");
   

3. Save and build the solution.

4. Press the F5 key or choose Start from the Debug menu.

   Now the form will be always displayed in French. If you changed the size of the button earlier to accommodate the longer French string, notice that the button size has also been persisted in the French resource file.

To manually add resource files to the project and edit them

1. On the Project menu, click Add New Item.

2. In the Templates box, select the Resources File template. Type the file name "WinFormStrings.resx" in the Name box. The file WinFormStrings.resx will contain fallback resources in English. These resources will be accessed whenever the application cannot find resources more appropriate to the UI culture.

   The file is added to your project in Solution Explorer and automatically opens in the XML Designer in Data view.

3. In the Data Tables pane, select data.

4. In the Data pane, click an empty row and enter strMessage in the name column and Hello World in the value column.

   You do not need to specify the type or mimetype for a string; they are used for objects. The type specifier holds the data type of the object being saved. The MIME type specifier holds the base type (base64) of the binary information stored, if the object consists of binary data.

5. On the File menu, click Save WinFormStrings.resx.

6. Do steps 1-5 twice more to create two more resource files named WinFormStrings.de-DE.resx and WinFormStrings.fr-FR.resx, with the string resources specified in the following table. The file WinFormStrings.de-DE.resx will contain resources that are specific to German as spoken in Germany. The file WinFormStrings.fr-FR.resx will contain resources that are specific to French as spoken in France.

   Resource file name	Name	Value
   WinFormStrings.de-DE.resx	strMessage	Hallo Welt
   WinFormStrings.fr-FR.resx	strMessage	Bonjour le Monde

To access the manually added resources

1. In the Code Editor, import the System.Resources namespace at the beginning of the code module.

   ' Visual Basic
   Imports System.Resources
   
   // C#
   using System.Resources;
   

2. In Design view, double-click the button to display the code for its Click event handler and add the following code. The ResourceManager constructor takes two arguments. The first is the root name of the resources — that is, the name of the resource file without the culture and .resx suffixes. The second argument is the main assembly.

   In this walkthrough, no namespaces are declared, so the first argument of the ResourceManager constructor can take the form of ProjectName.ResourceFileRootName. However, in a real-world application, you would set the DefaultNamespace property. In that case, you would need to declare the resource manager with the fully qualified root name of the resource file, including its namespace. For example, if the default namespace is MyCompany.MyApplication.MyComponent, the first argument of the ResourceManager constructor might be MyCompany.MyApplication.MyComponent.WinFormStrings.

   ' Visual Basic
   ' Declare a Resource Manager instance.
   Dim LocRM As New ResourceManager("WindowsApplication1.WinFormStrings", GetType(Form1).Assembly)
   ' Assign the string for the "strMessage" key to a message box.
   MessageBox.Show(LocRM.GetString("strMessage"))
   
   // C#
   // Declare a Resource Manager instance.
   ResourceManager LocRM = new ResourceManager("WindowsApplication1.WinFormStrings",typeof(Form1).Assembly);
   // Assign the string for the "strMessage" key to a message box.
   MessageBox.Show(LocRM.GetString("strMessage"));
   

   Note

   By default, the ResourceManager object is case-sensitive. If you want to do case-insensitive lookups so that "TXTWELCOME" retrieves the same resource as "txtWelcome", you can set the resource manager's IgnoreCase property to true. However, for performance reasons, it is best to always specify the correct case for your resource names. Doing case-insensitive resource lookups can cause performance problems.

3. Build and run the form. Click the button.

   The message box will display a string appropriate for the UI culture setting; or if it cannot find a resource for the UI culture, it will display a string from the fallback resources.

See Also

Tasks

How to: Set the Culture and UI Culture for Windows Forms Globalization