Export (0) Print
Expand All

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: one is to 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. The second way is to 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.

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 Resource File Generator (Resgen.exe).

To have Visual Studio generate resource files for you

  1. Create a new Windows Application named "WindowsApplication1". For details see Creating a Windows 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 or Form1.cs. Form1.resx is the resource file for the fallback 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 the Control Panel. For more information, see the Microsoft Globalization 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 Assembly Resource 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 namenamevalue
    WinFormStrings.de-DE.resxstrMessageHallo Welt
    WinFormStrings.fr-FR.resxstrMessageBonjour 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 messagebox
    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 messagebox
    MessageBox.Show(LocRM.GetString("strMessage"));
    
    Note   By default, the ResourceManager object is case-sensitive. If you wish 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

Setting the Culture and UI Culture for Windows Forms Globalization | Introduction to International Applications in Visual Basic and Visual C# | Walkthrough: Localizing Web Forms Pages | Globalizing and Localizing Applications | Security and Localized Satellite Assemblies

Show:
© 2014 Microsoft