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 VS2008; and you can insert data into the grid-style editor represented in Figure 12-1.

Figure 12.1. Figure 12-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 12-2 shows the window after choosing Images from the drop-down menu of the first toolbar icon (where Strings was selected in Figure 12-1) and after adding a few image files.

Figure 12.2. Figure 12-2

After adding a few strings and a few images, you can go to a .vb 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, that is, Messages in the example shown in Figure 12-1. Then, when you type Resources.Messages, it will list the string and image resources added earlier; and if you look closely at Figure 12-3, you'll also note that image resources are returned with the proper type of System.Drawing.Bitmap.

Figure 12.3. Figure 12-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 12-4. Note that you just select the resource you want from a prefilled drop-down list, so you don't need to type that yourself.

Figure 12.4. Figure 12-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.

You can create page-level resources by generating resource files, just as you do for global resources, but placing them under a folder named App_LocalResources (as opposed to App_GlobalResources used for global resources) located at the same level as the page to localize. For example, if the page is in the root folder, then you'll create the App_LocalResources under the root folder, but if the page is under /Test, then you'll create a /Test/App_LocalResources folder. This means you can have multiple App_LocalResources folders, whereas you can only have one App_GlobalResources folder for the whole site. The name of the resource filename is also fundamental, as it must be named after the page or control file for which it contains the localized resources, and include the culture name: for example, a culture-neutral resource file for Localization.aspx would be named Localization.aspx.resx, whereas it would be named Localization.aspx.it-IT.resx for the Italian resources. In Figure 12-5, you can see the organization of files in the Solution Explorer and the resource file being edited in the grid editor.

Figure 12.5. Figure 12-5

You can still use the Expressions dialog shown in Figure 12-4 to bind a control's property to an expression pointing to a localized resource: when you point to a page-specific resource you just leave the ClassKey textbox empty. Following is the generated expression:

<asp:Label ID="lblCopyright" runat="server"
   Text="<%$ Resources:CopyrightMessage % >" /  >

It differs from the expression shown in the previous section, as it doesn't include the class name; it just specifies the resource key. If you want to access local resources programmatically, you use the page's GetLocalResourceObject method, which takes the resource key name and returns an Object that you must cast to string or to the proper destination type (such as Bitmap if you stored an image):

string copyrightMsg = (string)this.GetLocalResourceObject("CopyrightMessage");

Even with localization expressions and local resources, localizing full pages will be a slow task if you need to create the expressions for dozens of controls, and things get worse if you need to localize multiple properties for the same control, such as Text, ToolTip, ImageUrl, NavigateUrl, and so on, which is often the case. To speed things up, Visual Studio offers the Tools

Figure 12-6 shows the resource editor for the Localization.aspx.resx local resource file after executing the Generate Local Resource command on the test page.

Figure 12.6. Figure 12-6

Besides the automatic generation of the resource file (or the addition of the resource items, if a resource file for that page was already present in the proper folder), what's even more interesting is that each control's declaration is modified as follows (note the code in bold):

<asp:Label ID="lblTitle" runat="server" Font-Size="X-Large" ForeColor="#C00000"
   meta:resourcekey="lblTitleResource1" Text="Localization Demo"
   Text="This page provides a nice demo of new ASP.NET 2.0 localization features"
/ >

A meta:resourcekey attribute is added to the declaration and is set to the prefix used in the local resource file to identify all localized properties of that control, such as lblTitleResource1.Text and lblTitleResource1.ToolTip. These are called implicit localization expressions (expressions used earlier are considered explicit). At runtime, the framework parses all resources and applies them to the properties of the corresponding controls, making the mapping of the first part of the key with the value of meta:resourcename. This means that the control's declaration is decorated with just a single new attribute, but may make multiple properties localizable. Later, if you want to localize a property that you didn't take into account originally, you just need to go to the resource editor and add an item following the naming schema described above, or edit its value if it already exists.

This behavior works with the page's title as well, originally defined in the @Page directive, which is modified as follows:

<%@ Page Language="C#" meta:resourcekey="PageResource1" ...other attributes... % >

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. Figure 12-7 shows the test page with the description text under the title placed inside a Localize control.

Figure 12.7. Figure 12-7

A LINK element can be added to the header of a page that specifies the hreflang attribute to associate an alternate version of the page in a specific language.

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.

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 12-8.

Figure 12.8. Figure 12-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 here:

Private Sub Application_BeginRequest(ByVal sender As Object, ByVal e As EventArgs)
    If Request.UserLanguages.Length  > 0 Then
        Dim culture As CultureInfo =
CultureInfo.CreateSpecificCulture(Request.UserLanguages(0))
        Thread.CurrentThread.CurrentCulture = culture
        Thread.CurrentThread.CurrentUICulture = culture
    End If
End Sub

In ASP.NET 2.0 and above, 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 12-9 shows what the same page looks like when loaded for the American English or Italian language selected in the browser.

Figure 12.9. Figure 12-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, from 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 Overloads Overrides Sub InitializeCulture()
    Dim culture As String = Helpers.GetCurrentCulture()
    Me.Culture = culture
    Me.UICulture = culture
End Sub

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, you'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.