Using Global Resources

Global resources are shared among all pages, controls, and classes, and are best suited to store localized data used in different places. When I say "data," I don't just mean strings, but also images, icons, sounds, and any other binary content. Although this was already possible in ASP.NET 1.x, VS.NET 2003 had worse graphical support for resource files. Now you access a resource file item (from the Add Item dialog box) under a folder named App_GlobalResources, which is a special folder, handled by the ASP.NET runtime and VS2005; and you can insert data into the grid-style editor represented in Figure 11-1.

Figure 11-1

If you click the arrow on the right side of the editor's Add Resource toolbar button, you will be able to create an image or icon, or insert any other file. Figure 11-2 shows the window after choosing Images from the drop-down menu of the first toolbar icon (where Strings was selected in Figure 11-1) and after adding a few image files.

Figure 11-2

After adding a few strings and a few images, you can go to a .cs file in the editor and type Resources: IntelliSense will pop up a drop-down list with the names of the resource files added to the project, i.e., Messages in the example shown in Figure 11-1. Then, when you type Resources.Messages, it will list the string and image resources added earlier; and if you look closely at Figure 11-3, you'll also note that image resources are returned with the proper type of System.Drawing.Bitmap.

Figure 11-3

This results in less manual typing, less probability of mistyping a resource or key name, and less casting.

Programmatic access of resources is necessary in some cases, particularly when you need to retrieve them from business or helper classes, and in this case you'll be happy to know that IntelliSense for dynamically compiled resources works also! However, when the resource will be used as the value for a property of a control on a page, there's an even easier approach: Just select the control in the page's graphical designer and click the ellipses button on the right side of the "(Expressions)" item in the Properties window. From the dialog box that pops up you can select the property you want to localize, select Resources as the expression type, and select then the resource class name and key, as shown in Figure 11-4. Note that you just select the resource you want from a pre-filled drop-down list, so you don't need to type that yourself.

Figure 11-4

After using this dialog box on an ASP control, if you go to the Source View, the declaration of the localized Label control will look like this:

<asp:Label ID="lblGreeting2" runat="server"
   Text='<%$ Resources:Messages, Greeting2 %>' / >

The Text property is set to a new localization expression (also called dollar-expression, because of the leading $ character), which at runtime will return the resource string from the Greeting2 item of the Messages class. You can also write these expressions yourself if you prefer coding your pages directly in the Source View (as I do). In either case, these expressions in the .aspx code are much better than manually writing C# code in the code-behind file, as you had to do with ASP.NET 1.x.

Localizing More Static Content

All content that you want to localize must be displayed by some sort of server-side control, such as the Label or Literal controls. You'll typically want to use a Literal over a Label if you don't need the appearance properties of a Label, either because you don't need to format the text or because the formatting is done through raw HTML tags present directly within the text, which is frequently the case for static text such as section and field titles, descriptions, copyright notices, and so on. An alternative to Literal is the new Localize control, listed in the last position under the Toolbox's Standard tab. If you declare it manually from the Source View, it's identical to a Literal. If, however, you work in the graphical designer, you'll notice that it doesn't have any properties listed in the Properties window beside the ID, not even a Text property. The way you fill it with text in the designer is to place the caret inside it and type the text directly. In Figure 11-7, you can see the test page with the description text under the title placed inside a Localize control: Note the caret symbol in the current insert position.

Figure 11-7

The declaration produced, after executing the Generate Local Resource command, is the following:

<asp:Localize ID="locDescription" runat="server"
   meta:resourcekey="locDescriptionResource1" Text="The page provides a demo... "
/>

As mentioned earlier, you can completely remove the Text property from the declaration, as it will be set from the localized resources at runtime.

Setting the Current Culture

Once you've modified your page with localization expressions for the various controls displaying static content, and you've created local or global resource files for the different languages you want to support, it's time to implement some way to enable users to change the page's language. One method is to read the Accept-Language HTTP header sent by the client to the server, which contains the array of cultures set in the browser's preferences, as shown in the dialog box in Figure 11-8.

Figure 11-8

In ASP.NET 1.x, you would set the current thread's CurrentCulture and CurrentUICulture properties to the first item of the UserLanguage array of the Request object, which would contain the first language in the list. You would execute this code in the Init or Load event of a page (typically a BasePage class, so that all others would inherit the same behavior), or from the Application's BeginRequest event, as shown below:

void Application_BeginRequest (Object sender, EventArgs e)
{
   if (Request.UserLanguages.Length > 0)
   {
      CultureInfo culture = CultureInfo.CreateSpecificCulture(
         Request.UserLanguages[0]);
      Thread.CurrentThread.CurrentCulture = culture;
      Thread.CurrentThread.CurrentUICulture = culture;
   }
}

In ASP.NET 2.0, however, you only need to set the culture and uiCulture attributes of the web.config file's <globalization> element to "auto", so that the user's favorite language will be retrieved and used automatically:

<configuration>
   <system.web>
      <globalization culture="auto" uiCulture="auto" />
      ...
   </system.web>
</configuration>

You can also specify these setting at the page-level, with the Culture and UICulture attributes of the @Page directive:

<%@ Page Culture="auto" UICulture="auto" ... %>

Figure 11-9 shows what the same page looks like when loaded for the American English or Italian language selected in the browser.

Figure 11-9

The "auto" setting only saves a few lines of code, but it's nice to have. In many situations, however, you'll prefer to set the culture by yourself anyway, because you'll need to extract the current culture from the user's profile, a session variable, or according to some other logic (I mentioned earlier that it's a good idea to let users specify their language of choice). If that's the case, the preceding code showing how to handle the application's BeginRequest is still valid, but you may actually prefer handling the application's PostAcquireRequestState event, so that the profile and session variables have been initialized already with the proper values. An even better solution is to override the page's new InitializeCulture method, to programmatically set the page's Culture and UICulture properties to the culture string (and not to a CultureInfo object as you do with the Thread properties). Here's an example:

protected override void InitializeCulture()
{
   string culture = Helpers.GetCurrentCulture();
   this.Culture = culture;
   this.UICulture = culture;
}

Helpers.GetCurrentCulture is a custom function that would return something like "en-US" or "it-IT" after reading the desired current culture from somewhere. In the "Solution" section, we'll read the culture from the user's profile, and override this method in the custom BasePage class, so that all pages inherit this behavior without the need to replicate the code more than once.