Localization with SiteMap

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 Germanyand "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.

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.

Resource availability in .Net 2.0

·           Strongly Typed Resources—At the core of the .NET Framework 2.0 release is support for strongly-typed resources that provide developers with Intellisense and simplify code required to access resources at runtime.

·           Managed Resource Editor—Visual Studio .NET 2.0 includes a new resource editor with better support for creating and managing resource entries including strings, images, external files, and other complex types.

·           Resource Generationfor Web Forms—Windows Forms developers have already enjoyed the benefits of automatic internationalization. Visual Studio 2005 will now support rapid internationalization by automatically generating resources for Web Forms, user controls, and master pages.

·           Improved Runtime Support—ResourceManager instances are managed by the runtime and readily accessible to server code through more accessible programming interfaces.

·           Localization Expressions—Modern declarative expressions for Web pages support mapping resource entries to control properties, HTML properties, or static content regions. These expressions are also extensible, providing additional ways to control the process of attaching localized content to HTML output.

·           Automatic Culture Selection—Managing culture selection for each Web request can be automatically linked to browser preferences.

·           Resource Provider Model—A new resource provider model allows developers to host resources in alternate data sources such as flat files and database stores, while the programming model for accessing those resources remains consistent.

 

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.

Creating Resource Files

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

  1. Resource Generatortool (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:
	2.             Label1.Text=Hello World!
	3.             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.

  1. 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.
  2. 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.

Localization

As an aid in localizing navigation UIs for users around the world, XmlSiteMapProvider offers built-in support for loading node titles and descriptions from string resources.

XmlSiteMapProvidersupports two types of localization expressions: implicit and explicit. Implicit expressions use resourceKey attributes to specify the root names of localization resources. The provider is responsible for parsing the localization expressions, whereas SiteMapNode performs the actual resource lookups at runtime (more on this in a moment). Root names are combined with attribute names to generate fully qualified resource names. The following node definition loads values for title and description from string resources named HomePage.title and HomePage.description in RESX files named Web.sitemap.culture.resx, where culture is a culture identifier such as fr or en-us:

<siteMapNode resourceKey="HomePage" title="Home" description="My home page" url="~/Default.aspx">

The default title and description are used if the resource manager can't find a RESX with the appropriate culture—for example, if the requested culture is fr, but the application contains RESX files only for de and us. The current culture—the one that determines which RESX resources are loaded from—is determined by the CurrentThread.CurrentUICulture property. The value of that property can be set programmatically; or, it can be declaratively initialized to the culture specified in each HTTP request's Accept-Language header, by setting UICulture to auto in an @ Page directive, or by setting uiCulture to auto in a <globalization> configuration element.

Explicit expressions don't rely on resourceKey attributes; instead, they use explicit resource names. In the following example, the node title comes from the resource named HomePageTitle in NavResources.culture.resx, whereas the node description comes from the resource named HomePageDesc (also in NavResources.culture.resx):

<siteMapNode title="$resources:NavResources,HomePageTitle,Home" description="$resources:NavResources,HomePageDesc,My home page" url="~/Default.aspx">

Once more, the current culture is defined by the value of CurrentThread.CurrentUICulture.

SiteMapNodeperforms the bulk of the work in loading node titles and descriptions from resources. All XmlSiteMapProvider has to do is parse out the resource keys—explicit and implicit—and pass them to SiteMapNode's constructor, as follows:

node = new SiteMapNode(this, key, url, title, description, roleList, attributeCollection, resourceKeyCollection, resourceKey);

For a node that uses an implicit expression, XmlSiteMapProvider passes the resource key in resourceKey. For a node that uses explicit expressions, XmlSiteMapProvider passes a collection of resource keys in resourceKeyCollection. Each item in the collection is either an attribute name/class name pair (for example, title and NavResources) or an attribute name/key name pair (for example, title and HomePageTitle). The parsing of explicit resource keys is handled by the private XmlSiteMapProvider.HandleResourceAttribute method, which is called by XmlSiteMapProvider.GetNodeFromXmlNode.

After the resource keys are provided to SiteMapNode's constructor, SiteMapNode handles the task of loading the resources. The key code is contained in the get accessors for SiteMapNode's Title and Description properties, which include logic for loading property values from string resources when implicit or explicit resource keys are provided.

 

Localizing Site-Map Data 

You can localize the following properties in a site map:

·                Title

·                Description

·                Custom properties that are contained in the Attributes collection

To localize the Title or Description properties of a site-map node by using an explicit expression

1.    In your site map, set the EnableLocalization property to true. For example, in a Web.sitemap file, change the <siteMap> node to look like the following code:

<siteMap enableLocalization="true">

2.    In your site map, change the value of the property that you want to localize to a resource string, such as the following case-sensitive line of code:

$resources:ClassName,KeyName,DefaultValue

For example, in a Web.sitemap file, your site-map node might look like the following example code.

<siteMapNode url="~/Home.aspx" title="$resources:SiteMapLocalizations,HomePageTitle" description="$resources:SiteMapLocalizations,HomePageDescription,Default description" myCustomAttribute="$resources: CustomLocalizations,MyCustomAttribute" />

The localized title and description are obtained from a file called SiteMapLocalizations.resx, by using the HomePageTitle and HomePageDescription resource keys. The localized custom attribute is obtained from a separate file called CustomLocalizations.resx.

Create your .resx files in a folder called App_GlobalResources in the root of your application. Within the .resx file, individual property values are indexed by the value of the key name.

3.       Create your .resx files in a folder called App_GlobalResources in the root of your application. Within the .resx file, individual property values are indexed by the value of the key name.

4.       If you need to localize strings for multiple languages, you can create additional .resx files with locale information included in the file name. For example, the French version of your resource file would be named SiteMapLocalizations.fr.resx.

 

To localize the Title or Description properties of a site-map node by using an implicit expression

1.    In your site map, set the EnableLocalization property to true. For example, in a Web.sitemap file, change the <siteMap> node to look like the following code:

<siteMap enableLocalization="true">

2.    In your site map, add an attribute called resourceKey to the site-map node that you want to localize by using the following case-sensitive line of code:

resourceKey="HomePage"

For example, in a Web.sitemap file, your <siteMap> node might look like the following code:

<siteMapNode url="~/Home.aspx" resourceKey="HomePage" title = "Default Title" description = "Default Description" />

The localized title and description are obtained from a file called Web.sitemap.resx using the HomePage.title and HomePage.description resource keys.

3.    Create your .resx file in a folder called App_GlobalResources in the root of your application. Within the .resx file, individual property values are indexed by the name. For the preceding example, the Web.sitemap.resx file might look like the following.

 

Note

Key names in global resource files should not include periods (.). However, periods are necessary in global resources that are referenced in site-map files when using implicit expressions. This is because of the resourceKey syntax. In some editing environments, such as Visual Web Developer, you might get a design-time error if you use a period in the key name. However, this shouldn't affect the ability to edit or save the file and can be ignored.

1.    If you need to localize strings for multiple languages, you can create additional .resx files with locale information included in the file name. For example, the French version of your resource file would be named Web.sitemap.fr.resx.

Localizing the URL Property in a Site Map

The URL property cannot be localized in a site map in the same way as the Title and Description properties.

To define different navigational structures based on a user's locale

1.    Define a different site-map file for each locale.

2.    Add each site map to the Web.config file.

3.    Programmatically switch to the appropriate Provider at run time. This is done by setting the SiteMapProvider property of the SiteMapDataSource object, or by setting the SiteMapProvider property of the SiteMapPath object, to the name of the provider.

Robust Programming

Explicit and implicit expressions can not be used in the same site-map file.

Posted by aravinda Monday, March 22, 2010 1:26:50 AM Categories: .Net Asp.Net Localisation

Comments

Comments are closed on this post.