Resources

Globalisation and localisation in ASP.NET

ASP.NET Resources

To display page in one of several languages could prompt user for their language and then use if..then..else statements to build display. This is complex and error prone.

Better to externalise items needing translation and connect code to these at runtime.

Resource files used to support multiple languages.

Contain language specific text for page (local resources), or entire site (global resources).

Access resource file based on machine or browser settings.

If no resource file exists then default language settings for site are used.

Local Resources

Specific to webpage

Stored in App_LocalResources folder - a sub folder of site, or any subfolder in site. If site has many folder then there will be App_LocalResources subfolder for each one.

Each resource file has same name as its page with .resx extension.

Default resource file could be called PageName.aspx.resx

Language specific resource file have name taking form PageName.aspx.languageid.resx, e.g. PageName.de.aspx.resx

Can support cultural differences by creating resource file with name taking form of PageName.aspx.languageid-cultureid.resx, e.g. PageName.en-us.aspx.resx

Resource File Contents

XML file including key-value pairs for defining resources, e.g.

<data name="PageResource1.Title" xml:space="preserve">

    <Value>Customer Lookup</value>

</data>

Generating Local Resources

Visual Studio can automatically generate default resource files.

Resources only generated for control elements, but not text outside the controls.

  1. Open webpage in Visual Studio
  2. Select Tools | Generate Local Resources. Visual Studio will
  • Create App_LocalResource folder
  • Generate resource file containing entries for string based properties.

Localising text outside controls

If text on page requires localisation its best to place it in control.

The <Asp:Localize> control renders no markup, only used to localize text typically found outside control.

The <Asp:Label> provides additional markup options, but works in similar fashion.

Attaching Controls and Resources Implicitly

Each page element associated with associated resource via the meta:resourceKey markup attribute.

ASP.NET uses this value to find items in resource file by finding keys that match the pattern Key.Property

Values from resource files will override any values specified in the markup.

Attaching Controls and Resources Explicitly

Can write markup to match control property to resource explicitly:

<asp:Button ID=ButtonFind" runat="server" Text="<%$ Resources:, ButtonFindResource1.Text %>"

Requires markup to be written for every control property.

Language-Specific Local Resources

First create default resource file.

Copy this file to create new resource file for target language, naming it accordingly.

Testing Resource Files

ASP.NET automatically detects preferred culture from info provided by web browser.

ASP.NET will set the Page.UICulture property based on the request.

Browser preferences sett at installation, but can be modified by users - from IE select Tools | Options | General | Languages | Appearance

Using Global Resources

Can be read from any page in website. Designed for accessing single resource from multiple location.

Still .resx files with same naming scheme.

Stored in App_GlobalResources folder in application root.

Must access global resources explicitly (implicit not supported).

Creating Global Resources

From website root, right click and "Add ASP.NET Folder", select App_GlobalResources

  1. Right click App_GlobalResources and "Add New Item"
  2. In "Add New Item" dialogue, select "Resource File" and provide a name.
  3. Open resource file and enter strings, images, etc. as appropriate.
  4. Copy file to create versions for different languages.

Attaching Control Properties to Global Resources

  1. Open page in Design View
  2. View properties for control
  3. Select Expressions property (in Data category), click on "..."
  4. From Bindable Properties list select property to bind to resource
  5. From Expression type list select Resource
  6. In Expressions Properties list, set ClassKey to name of global resource file (without extension) and set ResourceKey to name of resource within file

This builds up explicit accessor in form <%$ Resources:_ResourceFileName_, _ResourceID_ %>

Accessing Resource Values Programmatically

Use the Resources.ResourceFilename.Resource syntax, e.g. Resources.SharedText.WelcomeString;

Provides strongly types access

Class created based on file name (minus language and culture extensions).

ASP.NET also provides HttpContext.GetLocalResourceObject and HttpContext.GetLocalResourceObject methods which look for a resource file, read it and return requested resource, e.g.

Image1.ImageUrl = (String)GetGlobalResourceObject("WebResourcesGlobal", "LogoUrl");

HTML Layout Best Practices

  • Avoid using absolute positioning and sizes. Allow browser to position automatically
  • Use entire width and height of form, e.g <table width="100%"/>
  • Use separate table cell for each control. Allows text to wrap independently and ensures correct alignment when text flows in alternative directions.
  • Don't enable NoWrap on tables as other languages may require more space and so not display correctly
  • Don't use Align attribute in tables as can override layout in cultures using right-to-left text.
  • Decouple check boxes and radio boxes from their text. Placing descriptive text in separate cell allows wrapping to take place for longer translations.

Setting culture

Use browser settings as default, but allow user to override.

Use two page properties to set language and culture:

  • Culture - dictates result of culture-dependent functions, e.g. date, number, currency formatting. Can only define specific cultures, e.g. es-MX, fr-FR, etc. not neutral cultures.
  • UICulture - which global or local resources to be loaded. Accepts both neutral and specific cultures.

Define by overriding page's InitializeCulture method.

Typically done in base page from which other pages derive.

Specify culture decoratively at Page or Site level

To define for entire website add <globalization> section to Web.config:

<globalization uiculture="es" culture="es-MX" />

To declare for page set in page directive:

<%@ Page uiculture="es" culture="es-MX" %>

Downloads