ASP.NET 2.0 Quickstart Tutorial

To localize, or to be more specific, to create a web application that can be multi-lingual was a complex task prior to ASP.NET v2.0. If you used resource files (RESX) and the ResourceManager you would need to create your own satellite assemblies and perform your own lookup process which required considerable effort and code. ASP.NET v2, simplifies this process greatly and brings a wealth of features such as:

Auto detection of the ACCEPT_LANG or preferred culture of the client browser;
Declarative resource expressions to tie controls or their properties to resources;
Programmatic access to resources and strongly-typed resources;
Automatic compilation of RESX or RESOURCE files, with no requirement for satellites.

When building a multi-lingual web application, you benefit from a single page source that requires much less maintenance compared to the language separated site or page structure. ASP.NET v2 accomplishes this by providing a declarative model for resource handling through resource expressions. Resource expressions are a sub-feature of the overall expressions which can be thought of much like databinding expressions from v1. Expressions however, are parse-time property setters that do not require the user to explicitly call a method like DataBind().

ASP.NET v2 provides automatic support for resource (RESX or RESOURCE) files that follow a specific naming convention and that reside in specialized folders within the application. This allows you to add resource files without any compilation step or satellite assemblies and allows you to provide resources that can be scoped to a page or an application. The ASP.NET runtime uses the .NET Framework ResourceManager, to perform resources lookup. This model has many advantages such as the automatic fall-back mechanisms and custom culture support.

If RESX resource files are not your preferred source, you'll find the entire model extensible!

The samples described here can be executed for English-US(en-US), French(fr), German(de), Japanese(ja) and Arabic(ar). Other languages will defer to their fallback culture, or ultimately English-US. Refer to Setting a Preferred Language in Internet Explorer so that you can see the use of resources in action.

A Simple Example

The following example demonstrates the localization of a Label control in a page called LabelLocalization.aspx.

<%@ page uiculture="auto" culture="auto" %>
<form runat="server">
  <asp:Label ID="Label1" runat="server" text="<%$ Resources:Label1TextKey %>"
	font-name="<%$ Resources:Label1FontNameKey %>"/>
</form>

The page defines a Page directive with specific uiculture and culture attributes. The attribute values are automatic. This instructs ASP.NET to detect and set the current thread culture for the page execution based on the preferred culture of the client browser. The text and font-name properties of the Label are bound to resource expressions that resolve to a resourcekey which is used to perform assignment of the property to a value from, in this case, a page-level resource.

Alongside the LabelLocalization.aspx page is a peer folder called LocalResources. This is where the page-level resource(s) reside and are named appropriately for the page, for example:

LabelLocalization.aspx.resx. The culture-neutral resource file;
LabelLocalization.aspx.fr.resx. The culture-specific resource file, (French);
LabelLocalization.aspx.de.resx. The culture-specific resource file, (German).
LabelLocalization.aspx.ja.resx. The culture-specific resource file, (Japanese).
LabelLocalization.aspx.ar.resx. The culture-specific resource file, (Arabic).

These RESX files contain a keyname-value mapping. For example in LabelLocalization.aspx.resx

<data name="Label1TextKey">
  <value>Welcome to ASP.NET Localization</value>
</data>

Executing this page yields the rendering for the Label using a Text property from the resource for German, French, Japanese or other languages.

A Quick Note About Culture and UICulture

You've seen above that the Page directive specifies uiculture and culture attributes. These control 2 different aspects of localization. UICulture can be thought of as the physical UI, colors, fonts etc. Culture affects formatting, for example, numeric formats and date formats.

Resource Expressions

There are two forms of resource expressions, explicit and implicit.

Resource Expression form Description

Explicit <%$ Resources:[filename prefix,]resource-key[,"designerdefault" %>

The expression is used to define the value of a control property in declarative syntax and the resource-key, which is required, is used to map to the value from the resource. The filename prefix and designerdefault parameters are optional, but the filename specifies the name of a resource file(s) that resides in the application-level resources folder.

Implicit <asp:Label ID="Label1" runat="server" meta:resourcekey="resource-key-prefix" />

The expression used as an attribute on a control or object in declarative syntax and defines a resource-key-prefix which is used to perform many property assignments for the control. The resource file contains many potential resource-keys of the general form resource-key-prefix.Property. For example, Label1KeyPrefix.Text and Label1KeyPrefix.Font-name . All resources are obtained from page-level resources only. You can think of the expressions, therefore, as a short-hand notation for one to many control properties without explicitly defining the properties in the page.

Application-level and Page-level Resources

Application-level resources reside in a specialized folder called /Resources at the root of the application. All pages, user-controls etc. can access these resources so they typically are used for shared resources. The name of the resource file is used in explicit expressions, but also forms the namespace.classname for strongly-typed access under the Resources namespace in your application.

Page-level resources are defined in a peer-level /LocalResources folder. RESX files for example, follow the naming convention of the associated page, user-control or master-page, along with the culture definition. For example, foo.aspx will refer to the /LocalResources/foo.aspx.resx culture-neutral file and /LocalResources/foo.aspx.fr.resx and /LocalResources/foo.aspx.ja.resx culture-specific files. Only the associated page can notionally access these resources using the explicit or implicit resource expression. There is a programmatic method available to access these resources in code.

Using Explicit Expressions and Auto-detection

The following example demonstrates using the Page directive attributes uiculture="auto" and culture="auto". This performs automatic detection of the preferred language (culture) of the client browser. The Label and the Image control use explicit expressions with a resource-key and the page title and the directionality of the form are also expression-bound from resources.

VB Explicit Expressions and Page-level Resources

Using Implicit Expressions and Page-level Resources

This example uses implicit resource expressions. A GridView control is used to show data, and this control and its sub-objects also use implicit resource expressions. ASP.NET uses the default-culture resource file to determine which properties are localized for a control. Note: adding a new key to a culture-specific resource file will require a corresponding key entry in the culture-neutral resource file.

VB Implicit Expressions and Page-level Resources

Using Explicit Expressions and Application-level Resources

This example is similar to that above for explicit resource expressions and page-level resources, but it uses application-level resources. Application resources are identified by using the additional filename-prefix attribute in the expression's value.

VB Explicit Expressions and Application-level Resources

Programmatically Handling Application-level and Page-level Resources

This example shows the use of strongly-typed resources from the application-level resources location, as well as the helper methods GetPageResourceObject() and GetAppResourceObject() to obtain control property values.

VB programmatic Access and Resources

Localizing Static Content

Typically developers create a web application that contains static markup. This in itself may require localization. To support this, both at runtime and design-time, a new 'marker' tag is used called <localize runat="server">.

Localizing Static Content

Changing Internet Explorer's preferred language

In Internet Explorer:

Select the "Tools | Internet Options" command
Select the "Languages" button.
In the dialog that is shown, click on the "Add" button to add a new culture and select a new culture. Press "OK".
Ensure your preferred culture is at the top of the list. Select that culture and click "Move Up".
Click "OK" to exit the dialog.
Refresh the page using F5.

In order to view Japanese fonts or Arabic fonts, you'll potentially need to install the correct language pack for Internet Explorer. Refer to Internet Explorer Help Topics for more information.