ASP.NET 2.0 Unleashed

If you need to modify the text (or other content) in a page depending on a user's language, then you can take advantage of resource files. Each resource file can contain page text translated into a particular language.

The ASP.NET Framework supports two types of resource files: local and global resources. In this section, you learn how to use local resources. A local resource is scoped to a particular file such as an ASP.NET page.

Explicit Localization Expressions

The page in Listing 24.10 is a very simple page. It contains a button labeled "Click Here!" and displays the text "Thank You!" after you click the button.

Listing 24.10. SimplePage.aspx

<%@ Page Language="VB" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <script runat="server"> Sub btnSubmit_Click(ByVal sender As Object, ByVal e As EventArgs) lblMessage.Visible = True End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Simple Page</title> </head> <body> <form runat="server"> <div> <asp:Button Text="Click Here!" OnClick="btnSubmit_Click" Runat="server" /> <br /><br /> <asp:Label Text="Thank You!" Visible="false" Runat="server" /> </div> </form> </body> </html>

The page in Listing 24.10 displays the same text regardless of the language of the user visiting the page. If you want to display text in different languages for different users, then you need to make a few modifications to the page.

The page in Listing 24.11 is a localizable version of the same page.

Listing 24.11. LocalizablePage.aspx

<%@ Page Language="VB" UICulture="auto" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <script runat="server"> Sub btnSubmit_Click(ByVal sender As Object, ByVal e As EventArgs) lblMessage.Visible = True End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Localizable Page</title> </head> <body> <form runat="server"> <div> <asp:Button Text="<%$ Resources:ClickHere %>" OnClick="btnSubmit_Click" Runat="server" /> <br /><br /> <asp:Label Text="<%$ Resources:ThankYou %>" Visible="false" Runat="server" /> </div> </form> </body> </html>

Two types of changes were made to the page in Listing 24.11. First, notice that the <%@ Page %> directive includes a UICulture attribute that is set to the value auto. When a user requests the page, a resource file that matches the user's preferred browser language is loaded automatically.

Note

Don't confuse the Page UICulture property with the Page Culture property. The UICulture property determines which resource files are loaded for the page. The Culture property, on the other hand, determines how date, number, and currency values are formatted.

Second, notice that both the Button and Label controls have been modified. The Button control is declared like this:

<asp:Button Text="<%$ Resources:ClickHere %>" OnClick="btnSubmit_Click" Runat="server" />

The value of the Text property is a resource expression. This resource expression retrieves the value of an entry named ClickHere from the loaded resource file. This resource expression is considered to be an explicit resource expression because the property is explicitly set to the value of a particular resource entry.

After you localize a page, you can associate a resource file with the page. All the resource files that you want to associate with a page must be added to a special folder named App_LocalResources. You create the App_LocalResources folder in the same folder as the page that you want to localize. For example, if the page is located in the root of your application, then you would add the App_LocalResources folder to the root folder.

You associate a resource file in the App_LocalResources folder with a particular page by using the following file naming convention:

page name.[culture name].resx

For example, all the following resource files are associated with the LocalizablePage.aspx page:

LocalizablePage.aspx.resx LocalizablePage.aspx.es-PR.resx LocalizablePage.aspx.es.resx

The first resource file is the default resource file. If none of the other resource files match the user's language settings, then the contents of the default resource file are used.

The second resource file name includes the specific culture name es-PR (Puerto Rican Spanish). If a user's browser is set to Puerto Rican Spanish, then the contents of this resource file are loaded.

Finally, the third resource file name includes the neutral culture name es (Spanish). If a user's preferred language is Spanish, but not Puerto Rican Spanish, then the contents of this resource file are loaded.

You create a resource file when using Visual Web Developing by right-clicking an App_LocalResources folder, selecting Add New Item, and selecting Assembly Resource file. Visual Web Developer automatically displays an editor for the resource file. The editor enables you to enter name and value pairs. For example, the LocalizablePage.aspx.es.resx resource file contains the two name/value pairs in Listing 24.12.

Listing 24.12. App_LocalResources\LocalizablePage.aspx.es.resx

Name

Value

ClickHere

chasque aquí

ThankYou

¡Gracias!

Behind the scenes, resource files are XML files. You can open a resource file in Notepad and edit its contents. The ASP.NET Framework dynamically compiles resource files into assemblies in the background.

Implicit Localization Expressions

As an alternative to using explicit localization expressions, you can use an implicit localization expression. An implicit localization expression enables you to localize multiple control properties with one resource key.

The page in Listing 24.13 uses implicit localization expressions.

Listing 24.13. LocalizablePageImplicit.aspx

<%@ Page Language="VB" UICulture="auto" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <script runat="server"> Sub btnSubmit_Click(ByVal s As Object, ByVal e As EventArgs) lblMessage.Visible = True End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Localizable Page Implicit</title> </head> <body> <form runat="server"> <div> <asp:Button meta:resourceKey="btnSubmit" Text="Click Me!" ToolTip="Click to show message" OnClick="btnSubmit_Click" Runat="server" /> <br /><br /> <asp:Label meta:resourceKey="lblMessage" Text="Thank You!" Visible="false" Runat="server" /> </div> </form> </body> </html>

Notice that both the Button and Label control include a meta:resourceKey property. The value of this property represents a resource key in a local resource file.

For example, the resource file in Listing 24.14 contains three entries.

Listing 24.14. App_LocalResources\LocalizablePageImplicit.aspx.es.resx

Name

Value

btnSubmit.Text

chasque aquí

btnSubmit.ToolTip

Chasque aquí para demostrar el mensaje

lblMessage.Text

¡Gracias!

The first two entries set the Text and ToolTip properties of the btnSubmit control. The third entry sets the value of the Text property of the lblMessage property.

Warning

When you are ready to start localizing a page, always create a default localization file (for example, LocalizablePageImplicit.aspx.resx). If you don't create a default localization file, other culture-specific localization files are ignored.

There are two advantages to using implicit localization expressions over using explicit localization expressions. First, implicit expressions enable you to override multiple control properties by associating a single resource key with the control.

Second, by taking advantage of implicit localization expressions, you can more easily localize an existing website. You simply need to add the meta:resourceKey attribute to any control that you need to localize.

Using Local Resources with Page Properties

You can use resource expressions when setting page properties such as the page title. For example, the page in Listing 24.15 uses an explicit resource expression to set the page title.

Listing 24.15. PageExplicit.aspx

<%@ Page Language="VB" UICulture="auto" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title><asp:Literal Text="<%$ Resources:Title %>" runat="Server" /></title> </head> <body> <form runat="server"> <div> <h1>Page Explicit Localization</h1> </div> </form> </body> </html>

In Listing 24.15, the page title is created with a Literal control. The Literal control contains an explicit resource expression for the value of its Text property.

You also can use implicit resource expressions when setting the page title. This approach is illustrated by the page in Listing 24.16.

Listing 24.16. PageImplicit.aspx

<%@ Page Language="VB" UICulture="auto" meta:resourceKey="page" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Page Title</title> </head> <body> <form runat="server"> <div> <h1>Page Implicit Localization</h1> </div> </form> </body> </html>

Notice that the <%@ Page %> directive includes a meta:resourceKey attribute. If a local resource includes a page.Title entry, then the value of this entry is used for the title displayed by the page.

Retrieving Local Resources Programmatically

If you need to retrieve a local resource in your page code, then you can use the GetLocalResourceObject() method. For example, the page in Listing 24.17 grabs a welcome message from a resource file. The welcome message is used to format some text, and then the formatted text is displayed in a Label control.

Listing 24.17. ProgramLocal.aspx

<%@ Page Language="VB" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <script runat="server"> sub Page_Load() Dim welcomeMessage As String = CType(GetLocalResourceObject("welcomeMessage"), String) lblMessage.Text = String.Format(welcomeMessage, "Steve") end Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Program Local Resource</title> </head> <body> <form runat="server"> <div> <asp:Label Runat="server" /> </div> </form> </body> </html>

Notice that the result returned from the GetLocalResourceObject() must be cast to a string value. As the method name implies, the method returns an object and not a string value.

The resource file associated with the page in Listing 24.17, named ProgramLocal.aspx.es.resx, is contained in Listing 24.18.

Listing 24.18. App_LocalResources\ProgramLocal.aspx.es.resx

Name

Value

welcomeMessage

Welcome {0} to our website!

If someone's browser is set to Spanish as the preferred language, and the user requests the page, then the welcome message is retrieved from this resource file, the name Steve is added to the string, and the result is displayed in the browser (see Figure 24.8).

Figure 24.8. Retrieving a local resource programmatically.

You also can retrieve local resources in a component. Within a component, use the shared HttpContext.GetLocalResourceObject() method. For example, the component in Listing 24.19 grabs the entry named ClickHere from the local resource file that corresponds to the page named LocalizablePage.aspx.

Listing 24.19. LocalComponent.cs

[View full width]

Public Class LocalComponent Public Shared Function getResource() As String Return CType(HttpContext.GetLocalResourceObject("~/LocalizablePage.aspx" ,"ClickHere"), String) End Function End Class

Related

Категории