Localizing Applications for Multiple Languages ~ OneAoneJ

One can localize an ASP.NET website so that it supports multiple languages and cultures. For example, you might need to create both an English language and Spanish language version of the same website.

One approach to localization is to simply create multiple copies of the same website and translate each copy into a different language. This is a common approach when building ASP Classic (or even ASP.NET 1.1) websites. The problem with this approach is it creates a website maintenance nightmare. Whenever you need to make a change to the website—no matter how simple—you must make the change in each copy of the website. When building ASP.NET applications, you do not need to create multiple copies of a website to support multiple languages. Instead, you can take advantage of resource files. A resource file contains language-specific content. For example, one resource file might contain a Spanish version of all the text in your website, and a second resource file might contain the Indonesian version of all the text in your website.

Setting the Current Culture

Two main properties of the Page class have an effect on localization:

UICulture

Culture

The UICulture property is used to specify which resource files are loaded for the page. The resource files can contain all the text content of your pages translated into a particular language. You can set this property to any standard culture name.

The Culture property, on the other hand, determines how strings such as dates, numerals, and currency amounts are formatted. It also determines how values are compared and sorted. For example, by modifying the Culture property, you can display dates with language-specific month names such as January (English), Januar (German), or Enero (Spanish).

Both the UICulture and Culture properties accept standard culture names for their values. Culture names follow the RFC 1766 and RFC 3066 standards maintained by the Internet Engineering Task Force (IETF). The IETF website is located at www.IETF.org.

Here are some common culture names:

de-DE = German (Germany)

en-US = English (United States)

en-GB = English (United Kingdom)

es-MX = Spanish (Mexico)

id-ID = Indonesian (Indonesia)

zh-CN = Chinese (China)

Notice that each culture name consists of two parts. The first part represents the language code and the second part represents the country/region code. You can view the culture names supported by the .NET Framework by looking up the entry for the CultureInfo class in the Microsoft .NET Framework SDK documentation. It’s a really long list. The Culture property must always be set to a specific culture. This makes sense because, for example, different English speakers use different currency symbols. The UICulture property, on the other hand, can be set to either a neutral or specific culture name. Text written in Canadian English is pretty much the same as text written in U.S. English.

Setting a Culture Manually

You can set either the UICulture or Culture properties by using the <%@ Page %> directive. For example, the page in Listing sets both properties to the value id-ID (Indonesian).

LISTING Bagus.aspx

<%@ Page Language=”C#” Culture=”id-ID” UICulture=”id-ID” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

lblDate.Text = DateTime.Now.ToString(“D”);

lblPrice.Text = (512.33m).ToString(“c”);

}

</script>

<title>Bagus</title>

</head>

<body>

<div>

Today’s date is:

<br />

<asp:Label id=”lblDate” Runat=”server” />

<hr />

The price of the product is:

<br />

<asp:Label id=”lblPrice” Runat=”server” />

</div>

</form>

</body>

</html>

The page in Listing displays a date and a currency amount. Because the Culture property is set to the value id-ID in the <%@ Page %> directive, both the date and currency amount are formatted with Indonesian cultural conventions.

The date is displayed like this:

05 November 2005

The currency amount is displayed as an Indonesian Rupiah amount like this:

Rp512

Setting the Culture does not actually convert a currency amount. Setting a particular culture only formats the currency as appropriate for a particular culture. If you need to convert currency amounts, then you need to use a Web service: Conversion rates change minute by minute. See, for example, www.xmethods.com.

Instead of using the <%@ Page %> directive to set the Culture or UICulture properties, you can set these properties programmatically. For example, the page in Listing enables you to select a particular culture from a drop-down list of cultures.

LISTING SelectCulture.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

protected void btnSelect_Click(object sender, EventArgs e)

{

Culture = ddlCulture.SelectedValue;

}

void Page_PreRender()

{

lblDate.Text = DateTime.Now.ToString(“D”);

lblPrice.Text = (512.33m).ToString(“c”);

}

</script>

<title>Select Culture</title>

</head>

<body>

<div>

<asp:Label id=”lblCulture” Text=”Culture:” AssociatedControlID=”ddlCulture” Runat=”server” />

<asp:DropDownList id=”ddlCulture” DataTextField=”DisplayName” DataValueField=”Name”

DataSourceID=”srcCultures” Runat=”server” />

<asp:Button id=”btnSelect” Text=”Select” Runat=”server” OnClick=”btnSelect_Click” />

<asp:ObjectDataSource id=”srcCultures” TypeName=”System.Globalization.CultureInfo”

SelectMethod=”GetCultures” Runat=”server”>

<asp:Parameter Name=”types” DefaultValue=”SpecificCultures” />

</SelectParameters>

</asp:ObjectDataSource>

<hr />

Today’s date is:

<br />

<asp:Label id=”lblDate” Runat=”server” />

The price of the product is:

<br />

<asp:Label id=”lblPrice” Runat=”server” />

</div>

</form>

</body>

</html>

The DropDownList control in Listing is bound to an ObjectDataSource control, which retrieves a list of all the culture names supported by the .NET Framework. The culture names are retrieved during a call to the GetCultures() method of the CultureInfo class. When you click the button to select a culture, the btnSelect_Click() method executes and assigns the name of the selected culture to the page’s Culture property. When you select a new culture, the formatting applied to the date and currency amount changes. Several websites on the Internet display a page that requires the user to select a language before entering the main website. For example, the Federal Express website (www.FedEx.com) requires you to select a country before entering the website. You can take advantage of the Profile object to store a user’s preferred culture. That way, a user needs to select a culture only once and the culture is then used any time the user returns to your website in the future.

LISTING SelectCultureProfile.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

protected override void InitializeCulture()

{

Culture = Profile.UserCulture;

UICulture = Profile.UserUICulture;

}

protected void btnSelect_Click(object sender, EventArgs e)

{

Profile.UserCulture = ddlCulture.SelectedValue;

Profile.UserUICulture = ddlCulture.SelectedValue;

Response.Redirect(Request.Path);

}

void Page_PreRender()

{

lblDate.Text = DateTime.Now.ToString(“D”);

lblPrice.Text = (512.33m).ToString(“c”);

}

</script>

<title>Select Culture Profile</title>

</head>

<body>

<div>

<asp:Label id=”lblCulture” Text=”Culture:” AssociatedControlID=”ddlCulture” Runat=”server” />

<asp:DropDownList id=”ddlCulture” DataTextField=”DisplayName” DataValueField=”Name”

DataSourceID=”srcCultures” Runat=”server” />

<asp:Button id=”btnSelect” Text=”Select” Runat=”server” OnClick=”btnSelect_Click” />

<asp:ObjectDataSource id=”srcCultures” TypeName=”System.Globalization.CultureInfo”

SelectMethod=”GetCultures” Runat=”server”>

<asp:Parameter Name=”types” DefaultValue=”SpecificCultures” />

</SelectParameters>

</asp:ObjectDataSource>

<hr />

Today’s date is:

<br />

<asp:Label

id=”lblDate” Runat=”server” />

The price of the product is:

<br />

<asp:Label id=”lblPrice” Runat=”server” />

</div>

</form>

</body>

</html>

You should notice two things about the page in Listing. First, notice that the culture is set in the InitializeCulture() method. This method overrides the InitializeCulture() method of the base Page class and sets the UICulture and Culture properties by using the Profile object. Second, notice that the btnSelect_Click() handler updates the properties of the Profile object and redirects the page back to itself. This is done so that the InitializeCulture() method executes after a user changes the selected culture.

You can retrieve the value of the Accept-Language header by using the Request. UserLanguages property. For example, the page in Listing displays a list of the languages retrieved from a browser’s Accept-Language header.

LISTING ShowAcceptLanguages.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

bltAcceptLanguages.DataSource = Request.UserLanguages;

bltAcceptLanguages.DataBind();

}

</script>

<title>Show Accept Languages</title>

</head>

<body>

<div>

<asp:BulletedList id=”bltAcceptLanguages” Runat=”server” />

</div>

</form>

</body>

</html>

If you want to set the Culture or UICulture properties automatically by detecting the browser’s Accept-Language header, then you can set either of these properties to the value auto. For example, the page in Listing automatically displays the date and currency amount according to the user’s preferred language.

LISTING SelectCultureAuto.aspx

<%@ Page Language=”C#” Culture=”auto:en-US” UICulture=”auto:en-US”%>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_PreRender()

{

lblDate.Text = DateTime.Now.ToString(“D”);

lblPrice.Text = (512.33m).ToString(“c”);

}

</script>

<title>Select Culture Auto</title>

</head>

<body>

<div>

Today’s date is:

<br />

<asp:Label id=”lblDate” Runat=”server” />

The price of the product is:

<br />

<asp:Label id=”lblPrice” Runat=”server” />

</div>

</form>

</body>

</html>

In the <%@ Page %> directive in Listing, both the Culture and UICulture attributes are set to the value auto:en-US. The culture name that appears after the colon enables you to specify a default culture when a language preference cannot be detected from the browser. Don’t assume that all values of the Accept-Language header retrieved from a browser are valid culture names. Most browsers enable users to enter a “user-defined” language, which may or may not be valid.

Setting the Culture in the Web Configuration File

Rather than set the Culture and UICulture properties in each page, you can set these properties once in the web configuration file. Typically, you should take this approach because it makes your website easier to maintain. The web configuration file in Listing Sets both the Culture and UICulture properties to the value de-DE (German).

LISTING Web.Config

<system.web>

<globalization

culture=”de-DE”

uiCulture=”de-DE” />

</system.web>

</configuration>

Culture and ASP.NET Controls

The value of the Culture property automatically has an effect on the rendering behavior of ASP.NET controls such as the Calendar control. For example, Listing uses the ASP.NET Calendar control to display a calendar.

LISTING ShowCalendar.aspx

<%@ Page Language=”C#” Culture=”id-ID” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

<title>Show Calendar</title>

</head>

<body>

<div>

<asp:Calendar id=”Calendar1” Runat=”server” />

</div>

</form>

</body>

</html>

The Culture attribute in the <%@ Page %> directive is set to the value id-ID (Indonesian). When the calendar is rendered, Indonesian month names are displayed in the calendar. Using the CultureInfo Class The CultureInfo class contains information about more than 150 different cultures. You can use the methods of this class in your code to retrieve information about a specific culture and use the information when formatting values such as dates, numbers, and currency amounts. To represent a culture with the CultureInfo class, you can instantiate the class by passing a culture name to the class constructor like this:

Dim culture As New CultureInfo(“de-DE”)

You can also use any of the following methods of the CultureInfo class to retrieve information

about a culture or cultures:

. CreateSpecificCulture—Enables you to create a CultureInfo object by supplying the name of a specific culture.

. GetCultureInfo—Enables you to create a CultureInfo object by supplying an identifier, culture name, or CompareInfo and TextInfo object.

. GetCultureInfoByIetfLanguageTag—Enables you to create a CultureInfo object efficiently by supplying a culture name.

. GetCultures—Enables you to retrieve an array of cultures.

The CultureInfo class lives in the System.Globalization namespace. Before you can use the CultureInfo class, you need to import this namespace.

Using the CultureInfo Class to Format String Values

To this point, the culture has been set at the level of an individual ASP.NET page or the level of an entire ASP.NET application. However, you might need to take advantage of locale-specific formatting at a more granular level. You can use the CultureInfo class to format a particular value independent of the Culture set for the page.When you use the ToString() method to format dates, times, numbers, and currency amounts, you can supply an additional parameter that formats the value in accordance with a specific culture. For example, the page in Listing formats two sets of date and time values.

LISTING ToStringCulture.aspx

<%@ Page Language=”C#” %>

<%@ Import Namespace=”System.Globalization” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

// Get German Culture Info

CultureInfo gCulture = new CultureInfo(“de-DE”);

// Use culture when formatting strings

lblGermanDate.Text = DateTime.Now.ToString(“D”, gCulture);

lblGermanPrice.Text = (512.33m).ToString(“c”, gCulture);

// Get Indonesian Culture Info

CultureInfo iCulture = new CultureInfo(“id-ID”);

// Use culture when formatting strings

lblIndonesianDate.Text = DateTime.Now.ToString(“D”, iCulture);

lblIndonesianPrice.Text = (512.33m).ToString(“c”, iCulture);

}

</script>

<title>ToString Culture</title>

</head>

<body>

<div>

<h1>German</h1>

Today’s date is:

<br />

<asp:Label id=”lblGermanDate” Runat=”server” />

The price of the product is:

<br />

<asp:Label id=”lblGermanPrice” Runat=”server” />

<h1>Indonesian</h1>

Today’s date is:

<br />

<asp:Label id=”lblIndonesianDate” Runat=”server” />

The price of the product is:

<br />

<asp:Label id=”lblIndonesianPrice” Runat=”server” />

</div>

</form>

</body>

</html>

The first date and time is formatted with German cultural conventions, and the second date and time is formatted with Indonesian cultural conventions. Notice that two CultureInfo objects, corresponding to two cultures, are created in the Page_Load() method.

Comparing and Sorting String Values

Different cultures follow different conventions when comparing and sorting string values. If you need to compare or sort string values in your code, then you should use the String.Compare() method and optionally supply the method with an instance of the CultureInfo object.

Explicit Localization Expressions

The page in Listing.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 SimplePage.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

protected void btnSubmit_Click(object sender, EventArgs e)

{

lblMessage.Visible = true;

}

</script>

<title>Simple Page</title>

</head>

<body>

<div>

<asp:Button id=”btnSubmit” Text=”Click Here!” OnClick=”btnSubmit_Click” Runat=”server” />

<asp:Label id=”lblMessage” Text=”Thank You!” Visible=”false” Runat=”server” />

</div>

</form>

</body>

</html>

The page in Listing 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 is a localizable version of the same page.

LISTING LocalizablePage.aspx

<%@ Page Language=”C#” UICulture=”auto” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

protected void btnSubmit_Click(object sender, EventArgs e)

{

lblMessage.Visible = true;

}

</script>

<title>Localizable Page</title>

</head>

<body>

<div>

<asp:Button

id=”btnSubmit”

Text=”<%$ Resources:ClickHere %>”

OnClick=”btnSubmit_Click”

Runat=”server” />

<asp:Label id=”lblMessage” Text=”<%$ Resources:ThankYou %>” Visible=”false”

Runat=”server” />

</div>

</form>

</body>

</html>

Two types of changes were made to the page in Listing. 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. 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 id=”btnSubmit” 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

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 uses an explicit resource expression to set the page title.

LISTING PageExplicit.aspx

<%@ Page Language=”C#” UICulture=”auto” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

<title><asp:Literal Text=”<%$ Resources:Title %>” runat=”Server” /></title>

</head>

<body>

<div>

<h1>Page Explicit Localization</h1>

</div>

</form>

</body>

</html>

In Listing, 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.

LISTING PageImplicit.aspx

<%@ Page Language=”C#” UICulture=”auto” meta:resourceKey=”page” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

<title>Page Title</title>

</head>

<body>

<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 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 ProgramLocal.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

string welcomeMessage = (string)GetLocalResourceObject(“welcomeMessage”);

lblMessage.Text = String.Format(welcomeMessage, “Steve”);

}

</script>

<title>Program Local Resource</title>

</head>

<body>

<div>

<asp:Label id=”lblMessage” 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, named ProgramLocal.aspx. es.resx, is contained in Listing. 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.

Creating Global Resources

A local resource is scoped to a particular page. A global resource, on the other hand, can be used by any page in an application. Any localized content that you need to share among multiple pages in your website should be added to a global resource file. You create global resource files by adding the files to a special folder named App_GlobalResources. This folder must be located in the root of your application.

For example, the file in Listing is a global resource file. The page in Listing 26.21 uses the entries from the global resource file.

LISTING App_GlobalResources\Site.resx

Name Value

Title My website

LISTING ShowGlobalPage.aspx

<%@ Page Language=”C#” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

<title>

<asp:Literal id=”ltlTitle” Text=”<%$ Resources:Site,Title %>” Runat=”Server” />

</title>

</head>

<body>

<div>

<br />Page Content

<hr />

<asp:Literal id=”ltlCopyright” Text=”<%$ Resources:Site,Copyright %>” Runat=”Server” />

</div>

</form>

</body>

</html>

Just as you can with a local resource file, you can localize a global resource file by adding culture names to the filename. For example, the page in Listing is localized to Spanish.

LISTING 26.22 App_GlobalResources\Site.es.resx

Name Value

Title Mi Website

If you modify the UICulture attribute contained in the <%@ Page %> directive in Listing 26.21 to the value es, then the resource file in Listing will be used with the page. Alternatively, you can set UICulture to the value auto and change your browser’s language settings.

Retrieving Global Resources Programmatically

You can retrieve a global resource entry programmatically from any page by using the GetGlobalResourceObject() method. For example, the page in Listing grabs the Title entry from the Site resource file and displays the value of the entry in a Label control.

LISTING ProgramGlobal.aspx

<%@ Page Language=”C#” UICulture=”auto” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

lblMessage.Text = (string)GetGlobalResourceObject(“Site”, “Title”);

}

</script>

<title>Program Global</title>

</head>

<body>

<div>

<asp:Label id=”lblMessage” Runat=”server” />

</div>

</form>

</body>

</html>

The GetGlobalResourceObject() method requires two parameters: the name of the resource class and the name of an entry. The resource class corresponds to the global resource filename.

Using Strongly Typed Localization Expressions

The ASP.NET Framework automatically converts global resources into compiled classes behind the scenes. This enables you to use strongly typed expressions when working with global resources in your code. When you create a resource, a new class is added automatically to the Resources namespace. The class exposes all the entries of the resource file as properties. For example, the page in Listing retrieves the Title entry from the Site global resource file (Site.resx and its culture-specific variations).

LISTING ProgramGlobalTyped.aspx

<%@ Page Language=”C#” UICulture=”auto” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

void Page_Load()

{

lblMessage.Text = Resources.Site.Title;

}

</script>

<title>Program Global Typed</title>

</head>

<body>

<div>

<asp:Label id=”lblMessage” Runat=”server” />

</div>

</form>

</body>

</html>

Notice that you can use the following expression magically to refer to the Title entry in the Site resource file:

lblMessage.Text = Resources.Site.Title

Using the Localize Control

The ASP.NET Framework includes a control named the Localize control. This control is included in the Framework to make it easier to localize big chunks of text in a page. For example, the page in Listing uses the Localize control in the body of the page.

LISTING ShowLocalizeControl.aspx

<%@ Page Language=”C#” UICulture=”auto” %>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.1//EN”

“http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd”>

<title>Show Localize Control</title>

</head>

<body>

<div>

<asp:Localize ID=”locBodyText” meta:resourceKey=”locBodyText” Runat=”server”>

Here is the page body text

</asp:Localize> <br /><br />

<asp:Literal ID=”ltlBodyText” runat=”server”>

Here is some literal text

</asp:Literal>

</div>

</form>

</body>

</html>

The Localize control is very similar to the Literal control (it derives from the Literal control). In SourceView, there is nothing that distinguishes the two controls. The difference between the Localize control and Literal control is apparent only in DesignView.

Tuesday, June 11, 2013

Localizing Applications for Multiple Languages