Localizable Strings

To illustrate how the essential internationalization process works, here we localize a single string. Let's return to the hard-coded string you saw earlier:

 MessageBox.Show("Insufficient funds for the transfer"); 

Clearly, this line of code is in Englishand it can only ever be in English. We need to go through two phases to internationalize this code: First, we need to make this code localizable. Second, we need to localize it. To make the code localizable, we need to remove the string from the source code and place it in some other container that can be changed at runtime. The .NET Framework and Visual Studio have a ready-made solution to this problem: resx files. In Chapter 12, "Custom Resource Managers," we look at maintaining resources in locations other than resx files; for now, however, we use this simple, fast solution that Visual Studio naturally lends itself to. resx files are XML files that contain resources such as strings and bitmaps. To create a resx file in Visual Studio 2005, right-click the project in Solution Explorer; select Add, New Item...; and select Resource File (see Figure 3.4).

Figure 3.4. Adding a Resource File to a Project

The name of the resx file is important because it is used in the code to identify the resources. It can be any name that does not conflict with a name that Visual Studio has or will automatically create. For example, Form1.resx is not acceptable in a Windows Forms application that has a form called Form1. It is always wise to adopt a file-naming convention. I follow this convention:

The resx file always has the same name as the source file to which it relates, and is suffixed with "Resources." For example, TaxCalc.cs has an associated resx file called TaxCalcResources.resx. The suffix is important for two reasons. First, Visual Studio 2003 and 2005 automatically add resx files for Windows Forms (e.g., Form1.cs already has a Form1.resx), and this resx is considered to be under the control of Visual Studio. Second, Visual Studio 2005 can automatically create a strongly-typed class corresponding to a resx file, and this class is given a name that corresponds to the resx file. For example, if the TaxCalc.cs resources were placed in TaxCalc.resx, Visual Studio 2005 would create a corresponding strongly-typed resources class called TaxCalc, which would conflict with the existing TaxCalc class.

Visual Studio 2005 Windows Forms applications have a default resource file called Resources.resx. This resource file is for your own use; Visual Studio 2005 will not add or remove resources from it. The resource file itself is no different than a resource file that you create yourself, but it is present in every Visual Studio 2005 Windows Forms application. To maintain resources in it, either expand the Properties entry in the project in Solution Explorer and double-click Resources.resx, or double-click Properties and select the Resources tab. It is possible to delete or rename this file, but if you do so, the Resources property page will assume that the project no longer has a default resource file and will provide a warning to this effect.

After the resource file has been created, Visual Studio presents the Resource Editor (see Figure 3.5).

Figure 3.5. Visual Studio 2005 Resource Editor

The Resource Editor enables you to enter string, image, icon, audio, file, and other resources.

The Visual Studio 2003 Resource Editor enables you to enter string resources and, with a little effort, can be used to enter images. See the section entitled "Adding Images and Files in Visual Studio 2003" for details.

For Name enter a name by which this string resource will be identified (e.g., "InsufficientFunds"). You can find resource key name guidelines in the .NET Framework 2.0 help by looking for "Resource Names" in the index, but essentially, names should use Pascal case and should be descriptive but not verbose. For Value, enter the string itself (i.e, "Insufficient funds for the transfer"). Comment is used to hold additional information that the translator or other developers can use. Be aware, however, that the comment is maintained solely within the resx file. For reasons that will become clear shortly, the comment is not included in your compiled assemblies and is not shipped with your application. Enter a comment. The content of the comment depends upon who the comment is intended for. Mostly likely, it is a message to the translator/localizer and would contain instructions about the string's use, such as "InsufficientFunds is used in a MessageBox".

Visual Studio requires that resources must be saved for their changes to be included in the generated assembly.

How It Works

Let's stop for a moment to consider what will happen to this resource. Select the Form1Resources.resx file in Solution Explorer and take a look at it in the Properties Window. The Build Action property says that it is an Embedded Resource. This means that Visual Studio will identify the correct compiler for this resource type, compile it, and embed the result in the generated assembly. The correct compiler for resx files is a built-in version of resgen.exe. This compiler has many purposes, but one of them is to compile XML resx files into "resources" files. A "resources" file is a binary version of an XML resx file. You can perform this step manually if you want to see the command-line tool in action. Enter "resgen Form1Resources.resx" at the command prompt in the application's folder (make sure that you have saved the resx file in Visual Studio first):

 Read in 1 resources from "Form1Resources.resx" Writing resource file... Done. 

The result is a file called "Form1Resources.resources" that contains the compiled resources. You can open this file in Visual Studio (select File, Open, File... and enter the filename). Visual Studio uses its Binary Editor to show the file; you can see that the comment is nowhere in the file.

Visual Studio embeds the compiled output in the generated assembly using a build task that is a wrapper for the Assembly Linker (al.exe; see Chapter 14, "The Translator," for more details). You can see this using IL DASM (.NET's IL Disassembler). Open the generated assembly (i.e., WindowsApplication1.exe) and double-click the MANIFEST enTRy. Scroll down until you come to the following line:

 .mresource public WindowsApplication1.Form1Resources.resources 

".mresource" identifies that it is an embedded resource. As mentioned before, the name is important. Notice that it is prefixed with the application's namespace, "WindowsApplication1," and it is suffixed with ".resources" (because that was the resulting name after the resx file was compiled). Although there is little value in doing so, you could perform the same steps as Visual Studio manually by maintaining the resx files outside Visual Studio, compiling them into binary resources manually using resgen.exe, and embedding the resources in the generated assembly using the Assembly Linker (al.exe) tool.

At this stage, we have a WindowsApplication1.exe assembly that has an embedded resource called "WindowsApplication1.Form1Resources.resources," which contains a single string called "InsufficientFunds," which has a value of "Insufficient funds for the transfer." We need a way to retrieve this string from the embedded resource. For this, we need a Resource Manager.