Localization Made Easy with ASP.NET 2.0

Share |

 

In this article, I cover the basics of the globalization and localization support in ASP.NET 2.0. I have included a setup file that creates a Web site with samples for this article.

Globalization and Localization

Globalization is the process of designing your application so that it is possible later to have it translated and support multiple cultures. So, here you might not even actually make any translations but are making the application ready for it. Once you have globalized your application and now want to translate it into a specific culture, the translation process is called localization.

To globalize your application, the most important change to be done is that instead of hard-coding things such as display strings, move them to resource files. You then can set the control properties by reading the resource files. When you want to localize your application, have the resources translated to the languages you want to support. This will be covered in detail in this article.

The Difference Between Culture and Language

Culture consists of language plus the country/region. Culture is usually denoted by a combination of a two-letter lowercase code (called culture code) denoting the language and a two-letter uppercase code (called sub-culture code) denoting the country or region. For example, "de-DE" for German in Germany and "de-AT" for German in Austria (even though the language is the same, they are different cultures!).

Note: A neutral culture is a culture that is associated with a language but not with a country/region, for example, "de" for German.

Culture affects not only things like which language a particular string is shown but also things like the date format used, the decimal separator, currency symbol, and so on.

Culture and UICulture

In ASP.NET, you can set to two culture values: the Culture and UICulture properties. The Culture value determines things such as date, number, currency formatting, and so on. For example, it is the Culture setting that decides whether the date is in the dmy format or mdy format and what names to use for the month and for numeric values what the decimal separator is. The UICulture value determines which resources are loaded for the page. So, it controls things like which translated text to show. In most cases, you will set Culture and UICulture to the same culture.

Culture is set at the thread level by setting the CurrentCulture and CurrentUICulture properties of the thread. You either can set it directly or ASP.NET will set it for you.

In an ASP.NET application, culture can be set in one of these three ways:

1. Set it declaratively: In the web.config file or in the @Page directive in the page, you can specify the culture as shown:

   web.config: <globalization uiCulture="es-MX" culture="en-US" />

   @Page Directive: <%@ Page  UICulture="es-MX" Culture="es-MX" %>

   
   
2. From the client browser's language setting: Here, the user can specify their language of choice through the Languages option in their browser. To see a live example, change your languages option and view the GoogleMail login page. Notice how they change the display language accordingly.
   

   Note: For ASP.NET to use the browser language setting, you need to set the uiCulture and culture settings of web.config and/or the @Page directive to "auto."

   
   

   
   

   Figure 1a: Setting Languages options for Internet Explorer (IE)
   

   
   

   Figure 1b: Setting Languages option for Mozilla FireFox

Set it programmatically: In most cases, you will need to give an explicit way on your Web site for the user to select their language of choice. In such cases, you need to set the culture programmatically. Set these in the InitializeCulture method for the page.

Thread.CurrentThread.CurrentCulture =

   CultureInfo.CreateSpecificCulture(selectedLanguage);

Thread.CurrentThread.CurrentUICulture =

   new CultureInfo(selectedLanguage);

Note: If none of the above are set, ASP.NET will set the Culture and UICulture to that in the Regional Settings of the Web server.

Resource Files

To facilitate localization into different cultures, move strings you want to translate and localizable controls properties to a resource file. For example, if you want to change the string displayed in a Label and its ForeColor depending on the culture, you should move them to a resource file.

The resource file is an XML file and has a resx extension. Each resource in the resx file is in the form of a key-value pair. When you create resource files, start by creating a base .resx file. This is the default, or fallback resource file. For each culture that you want to support, create a copy of the base file and change the name so that it has the same basic file name, but with the culture name as part of it. For example, you might create the following files:

• WebResources.resx: The base resource file. This is the default, or fallback resource file
  
• WebResources.es.resx: A resource file for Spanish
  
• WebResources.es-mx.resx: A resource file for Spanish (Mexico)
  
• WebResources.de.resx: A resource file for German

At run time, ASP.NET uses the resource file that is the best match for the processing thread's CurrentUICulture property (I earlier described the ways in which this property gets set in ASP.NET). For example, if the current UI culture is Spanish (Mexico), resources from WebResources.es-mx.resx will be used. If it's Spanish (Costa Rica), ASP.NET will use WebResources.es.resx as its the best match. If the current UI culture is Swedish (Finland), which has no match in the above case, ASP.NET will use WebResources.resx as its the fallback resource file.

Local and Global Resource Files

Resource files are of two types: local resource files and global resource files.

Local resource files are specific to a single ASP.NET Web page, master page, or user control (.aspx, .master, or .ascx file). The resources in these files can be used only for that ASP.NET Web file. These resource files are put into the special ASP.NET App_LocalResources folder. A local resource file is named after the ASP.NET Web file; for example, the resource file for the Home.aspx Web page could be Home.aspx.resx, Home.aspx.es-mx.resx, and so on.

Note: Each sub-folder of the Web site can have its own App_LocalResources folder.

The resources in a global resource file can be read from any page or code in the Web site. These resource files are put into the special ASP.NET folder App_GlobalResources. This folder exists at the root of the ASP.NET application. Any .resx file that is in the App_GlobalResources folder has global scope.

Figure 2: Resource folders and resource files in a Web site as seen in Solution Explorer

Creating Resource Files

You can create a new resource file in any of the following ways:

Resource Generator tool (Resgen.exe): You can use this tool to help you generate the XML resouce file. To use this, place the key-value pairs in a text file; for example:

Label1.Text=Hello World!
Label1.ForeColor=Blue

You then can use the Resource Generator to generate an XML resource file from this text file. You then can copy this resx file into the global or local resource folder.

Using the Generate Local Resource option: You can use this option in Visual Studio 2005 to generate local resources for a Web page (.aspx, .master, or .ascx file). Open your page in design view and run this tool. It will generate the base (default) resx file for your page. The tool will move all localizable properties of controls on your page, such as the TextBox's Text property, Label's ForeColor property, and Page's Title property and so on, to the resource file. You then can delete those entries you do not wish to localize.

Manually: You can add an empty resource file by using the Add New Item option of Visual Studio. You can add resource entries to this file by opening them in Visual Studio's resource editor.

Setting Control Properties to Use Localized Resource Values

Once you have moved the control properties you want to localize to the resource file, you need to make changes in your page file or in the code-behind classes so that it picks up property values from the resource file. You might use resources to set the Text property of a Label control, instead of hard-coding the property to a specific string.

You can set the control properties by using localized values from resources in the following ways:

Implicit Localization

In this method, you don't set control properties one by one. Here, ASP.NET reads the resource file and sets all matching properties. For example, here is a Label control that uses implicit localization:

<asp:Label ID="MyLabel" meta:resourcekey="MyLabel" />

Here is a resource file with some properties set for this control:

MyLabel.Text=User Name
MyLabel.ForeColor=Blue

At runtime, ASP.NET takes the resourcekey and picks all properties set in the resource file (using the syntax resourcekey.PropertyName).

Implicit Localization can be used only to read values from local resource files.

Note: When you use the Generate Local Resource option to generate resources, Visual Studio automatically places the resourcekey tag in the aspx file.

Explicit Localization

Here, you explicitly set the control property to read a value from a local or global resource file. To set the property, you use a resource expression. The synatx is as follows.

To read from a global resource file:

<asp:Button ID="Button1" runat="server"
            Text="<%$ Resources:MyGlobal1, Button1Caption %>" />

To read from a local resource file:

<asp:Button ID="Button1" runat="server"
            Text="<%$ Resources: Button1Caption %>" />

Setting it programmatically

Use the GetLocalResourceObject or GetGlobalResourceObject method to read resources from a global or local resource file, respectively.

Button1.Text = GetLocalResourceObject("Button1.Text").ToString();
Button1.Text = GetGlobalResourceObject("Button1.Text").ToString();

Note: Each global resource gets compiled into a class under the Resources namespace. You can use this class to read resource values using strong typing. For example,

CompanynameLabel.Text = Resources.MyGlobal1.CompanyName;

Steps to Localizw an ASP.NET Application

You can follow these steps to localize your ASP.NET application:

Decide how you will let the users specify their culture of choice. You either could give them an explicit way to choose or take the culture specified in their browser, or a combination of the two.

Move the things you want to localize, such as the strings displayed on the Web pages and maybe even the images shown, to local or global resource files.

Change your Web page or code-behind classes (or both) to get their localized property values from resource files instead of hard-coding them.

Get the resources translated into the cultures you want to support.

Some Useful Links

1. MSDN Documentation covers the topic in detail: Globalizing and Localizing Applications


2. The Localization section in the Quickstart Tutorials (includes very good samples): Internationalizing Your Application


3. The best practices to follow when developing world-ready applications: Best Practices for Developing World-Ready Applications

BACKLINK

Technorati Tags: Technorati, Increasing, Authority, Rank, Blogging, Technology, Source Code, ASP.NET Tip: Persistent Logins Under ASP.NET 2.0