ASP.NET Resource Files
When you work with ASP.NET, resources are handled by resource files. A resource file is an XML-based file that has a .resx extension. You can have Visual Studio help you construct this file. Resource files provide a set of items that are utilized by a specified culture. In your ASP.NET applications, you store resource files as either local resources or global resources. The following sections describe how to use each type of resource.
Making Use of Local Resources
You might be surprised how easily you can build an ASP.NET page so that it can be localized into other languages. In fact, the only thing you need to do is build the ASP.NET page as you normally would and then use some built-in capabilities from Visual Studio to convert the page to a format that enables you to plug in other languages easily.
To see this in action, build an ASP.NET empty web application called ProVB_Localization. Next, add a new web form called a Default.aspx page. Note that a few simple controls have been added. This page will be referred to later in this chapter as the “ASP.NET page code block.” Keep in mind that the downloaded code will not match the initial code snippet shown here because this chapter modifies this code to support multiple languages (code file: Default.aspx):
<%@ Page Language="vb" AutoEventWireup="false" CodeBehind="Default.aspx.vb"
Inherits="ProVB_Localization._Default" %>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title></title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label ID="Label1" runat="server"
Text="What is your name?"></asp:Label><br />
<br />
<asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
<asp:Button ID="Button1" runat="server" Text="Submit Name" /><br />
<br />
<asp:Label ID="Label2" runat="server"></asp:Label>
</div>
</form>
</body>
</html>
As you can see, there is not much to this page. It is composed of a couple of Label controls, as well as TextBox and Button controls. Update the click event handler for Button1 to set the Label2.Text property text to the TextBox1.Text property value. This way, when users enter their name into the text box, the Label2 server control is populated with the inputted name.
The next step is what makes Visual Studio so great. To change the construction of this page so that it can be localized easily from resource files, ensure that you are on the .aspx page and not the code file. Next, using the Visual Studio menu, select Tools ⇒ Generate Local Resource. Note that you can select this tool only when you are editing the .aspx page.
Figure 15.11 Folder to hold application cultural resources
Selecting Generate Local Resource from the Tools menu causes Visual Studio to create an App_LocalResources folder in your project if you don't have one already. A .resx file based upon this ASP.NET page is then placed in the folder. For instance, if you are working with the Default.aspx page, then the resource file is named Default.aspx.resx (see Figure 15.11).
Right-click on the .resx file; select View Code. If View Code isn't present on your default menu, select Open With; you'll get a dialog with a list of editor options. From the Open With dialog, select the XML (Text) Editor as the program to open this file using the OK button. After doing this, you should find the View Code option on the context menu for this file. When the .resx file opens, you'll notice that the .resx file is nothing more than an XML file with an associated schema at the beginning of the document. The resource file that is generated for you takes every possible property of every translatable control on the page and gives each item a key value that can be referenced in your ASP.NET page. Looking at the page's code, note that all the text values you placed in the page have been retained, but they have also been placed inside the resource file. Visual Studio changed the code of the Default.aspx page in two places as follows (code file: Default.aspx):
<%@ Page Language="vb" AutoEventWireup="false" CodeBehind="Default.aspx.vb"
Inherits="ProVB_Localization._Default" culture="auto"
meta:resourcekey="PageResource1" uiculture="auto" %>
<div>
<asp:Label ID="Label1" runat="server"
Text="What is your name?" meta:resourcekey="Label1Resource1">
</asp:Label><br />
<br />
<asp:TextBox ID="TextBox1" runat="server"
meta:resourcekey="TextBox1Resource1"></asp:TextBox>
<asp:Button ID="Button1" runat="server" Text="Submit Name"
meta:resourcekey="Button1Resource1" /><br />
<br />
<asp:Label ID="Label2" runat="server" meta:resourcekey="Label2Resource1">
</asp:Label>
</div>
From this bit of code, you can see that the Culture and UICulture attributes have been added to the @Page directive with a value of auto, thus, enabling this application to be localized. In addition, the attribute meta:resourcekey has been added to each of the controls, along with an associated value. This is the key from the .resx file that was created on your behalf. Double-clicking on the Default.aspx.resx file opens the resource file in the Resource Editor, shown in Figure 15.12, built into Visual Studio. Keep in mind the code download will have additional settings not shown if you are working along with the chapter.
Figure 15.12 Editing default resource mappings
Note that a few properties from each of the server controls have been defined in the resource file. For instance, the Button server control has its Text and ToolTip properties exposed in this resource file, and the Visual Studio localization tool has pulled the default Text property value from the control based on what you placed there. Looking more closely at the Button server control constructions in this file, you can see that both the Text and ToolTip properties have a defining Button1Resource1 value preceding the property name. This is the key that is used in the Button server control shown earlier.
<asp:Button ID="Button1" runat="server" Text="Submit Name" meta:resourcekey="Button1Resource1" />
In the following aspx source, a meta:resourcekey attribute has been added to a Button control. In this case it references Button1Resource1. All the properties using this key in the resource file (for example, the Text and ToolTip properties) are applied to this Button server control at run time.
Adding Another Language Resource File
The Default.aspx.resx file created in the last section is used by the application as the default or invariant culture. No specific culture is assigned to this resource file. If for a given request no culture can be determined, then this is the resource file that is utilized. To add another resource file for the Default.aspx page that handles another language altogether, right click the App_LocalResources folder and select Add Í Resources File from the context menu. Use the name Default.aspx.fi-FI .resx for your new file. Next click on the top left corner of your original .resx file, which will select all, then right-click and select copy. Now return to your newly created file and paste the contents into your file. Finally give the following keys the values shown to make a Finnish-language resource file:
Button1Resource1.Text Lähetä Nimi Label1Resource1.Text Mikä sinun nimi on?
Once you have created this file, take an additional step and assign a value to the Label2Resource1 .Text entry. The Default.aspx.resx file should have the following key value pair:
Label2Resource1.Text Hello
You can add a value to the same key in the Default.aspx.fi-FI.resx file as shown here:
Label2Resource1.Text Hei
You now have resources for specific controls, and a resource that you can access later programmatically.
Finalizing the Building of the Default.aspx Page
Finalizing the Default.aspx page, you want to add a Button1_Click event so that when the end user enters a name into the text box and clicks the Submit button, the Label2 server control provides a greeting pulled from the local resource files. When all is said and done, your default page should have a code-behind element that matches the following snippet:
Label2.Text = GetLocalResourceObject("Label2Resource1.Text") &
" " & TextBox1.Text
In addition to pulling local resources using the meta:resourcekey attribute in the server controls on the page to access the exposed attributes, you can also access any property value contained in the local resource file by using the GetLocalResourceObject. When using GetLocalResourceObject, you simply use the name of the key as a parameter, as shown here:
GetLocalResourceObject("Label2Resource1.Text")
With the code from the Default.aspx page in place and the resource files completed, you can run the page, entering a name in the text box and then clicking the Submit Name button to get a response, as shown in Figure 15.13.
Figure 15.13 Displaying the form in English
What happened behind the scenes that caused this page to be constructed in this manner? First, only two resource files—Default.aspx.resx and Default.aspx.fi-FI.resx—are available. The Default.aspx.resx resource file is the invariant culture resource file, whereas the Default.aspx.fi-FI.resx resource file is for a specific culture (fi-FI). Because the browser requesting the Default.aspx page was set to en-US as the preferred culture, ASP.NET found the local resources for the Default.aspx page. From there, ASP.NET checked for an en-US-specific version of the Default.aspx page. Because there isn't a specific page for the en-US culture, ASP.NET checked for an EN-(neutral culture)-specific page. Not finding a page for the EN neutral culture, ASP.NET was then forced to use the invariant culture resource file of Default.aspx.resx, producing the page shown in Figure 15.13.
If you now set your IE language preference as fi-FI and rerun the Default.aspx page, you'll see a Finnish version of the page, as shown in Figure 15.14.
Figure 15.14 Displaying the form in Finnish
In this case, having set the IE language preference to fi-FI, you are presented with this culture's page instead of the invariant culture page presented earlier. ASP.NET found this specific culture through use of the Default.aspx.fi-FI.resx resource file.
You can see that all the control properties that were translated and placed within the resource file are utilized automatically by ASP.NET, including the page title presented in the title bar of IE.
Neutral Cultures Are Generally Preferred
When you are working with the resource files from this example, note that one of the resources is for a specific culture. The Default.aspx.fi-FI.resx file is for a specific culture—the Finnish language as spoken in Finland. Another option would be to make this file work not for a specific culture, but instead for a neutral culture. To do so, simply name the file Default.aspx.FI.resx. In this case, it doesn't make any difference because no other countries speak Finnish; but it would make sense for languages such as German, Spanish, or French, which are spoken in multiple countries.
For instance, if you are going to have a Spanish version of the Default.aspx page, you could definitely build it for a specific culture, such as Default.aspx.es-MX.resx. This construction is for the Spanish language as spoken in Mexico. With this in place, if someone requests the Default.aspx page with the language setting of es-MX, that user is provided with the contents of this resource file. If the requester has a setting of es-ES, he or she will not get the Default.aspx.es-MX.resx resource file, but the invariant culture resource file of Default.aspx.resx. If you are going to make only a single translation for your site or any of your pages, construct the resource files to be for neutral cultures, not specific cultures.
If you have the resource file Default.aspx.ES.resx, then it won't matter if the end user's preferred setting is set to es-MX, es-ES, or even es-AR—that user gets the appropriate ES neutral-culture version of the page.
Localization for Windows Store Apps
Rather than having just a generic set of tools, when working with Visual Studio 2012 on Windows 8 Microsoft has created a separate set of language-specific tool kits. Called the “Multilingual App Toolkit for Visual Studio 2012” these kits (which vary by language) provide you the tools to help you localize your Windows Store application. They provide translation support, management of resource files and editor tools.
Before you work at localizing a Windows Store application, you need to install a copy of this toolkit on your Windows 8 development machine. Next load the solution containing the project you want to localize and select that project in the Solution Explorer. With the project selected you'll find that the top option on the Tools menu for Visual Studio is “Enable Multilingual App Toolkit.”
Selecting that option will add a new folder to your solution called MultilingualResources. By default within this folder you will see a newly created Pseudo Language file. This .xlf file is used to hold a series of test strings associated with your custom localization efforts. If in a brand new application you double-click on this file you'll find that the Multilingual Editor opens as shown in Figure 15.15.
Figure 15.15 Multilingual Editor for Windows Store apps
Windows Store applications use a combination of .xlf file extensions for the language resources and .resw files to define the resources. The .xlf file extension relates to the industry standard XLIFF localization interchange file format. This format, which is defined on the www.oasis-open .org website, describes a standard extensible XML vocabulary that allows for easy interchange of translation files.
These files are assigned a default source and target language. Then they apply xml tags within a trans-unit structure to define the source and target strings for translation. Each trans-unit is named and has the potential to include additional alternative language definitions that essentially allow you to provide multiple target translations for each source string.
Unlike the previously described .resx files, Windows Store applications use .resw files. The good news is that these file formats are very similar, so similar, in fact, that the easiest way to transfer a .resx file to a Windows application is to create the necessary folders in your application and then copy in the .resx file and rename it as an .resw file. That will transfer your resource mappings. However, you will place only a single .resw file in your project, because you'll leverage the .xlf files and language editors to handle your translations.
Once you've added a .resw file to your project, you can then choose to add additional language. Right-click on the project file that you are looking to localize. Within the context menu you will find a new option to “Add Translation Languages.” Selecting this option will open the dialog shown in Figure 15.16, from which you can select the languages you would like to support.
Figure 15.16 Selecting languages for a Windows Store app
As shown in Figure 15.16, there is the option to select the neutral language (es) or to specify a culture and language that you would like to target. Each language you add will create a separate .xlf file to your multilingual resources folder in your project. You can then use the Multilingual Editor to create and maintain your translations.