Mark Gilbert's Blog

Science and technology, served light and fluffy.

How resourceful of you (Part 1 of 2)

One of the coolest features in ASP.NET 2.0 is the mechanism for accessing resources when localizing an application.  Once you have the resources (RESX) file built, access to the resources can be completely done in the markup:

<asp:Literal runat=”server” Text=”<%$ Resources:MyApp, PageTitle %>” />

In this example, the Literal is referencing a resource file called something like MyApp.resx in the App_GlobalResources folder of your application, and a resource with the name of “PageTitle”.  This post is more about how these resources are applicable in building a SharePoint 2007 master page or page layout, so I’ll be assuming that you already how to apply this technology in a straight-ASP.NET 2.0 application.  Here are a couple of links that explain ASP.NET 2.0 resources in more depth:

For the remainder of this post, “web app” should be taken to mean the SharePoint web application, as seen by IIS.  Normally, all of the directory structure that you set up in SharePoint is virtual, but when you create a web application (the top-most level for the SharePoint structure), you get an IIS virtual directory, as well as a “real” one on the file system.  The root directory for the web app is:

{DriveLetter}:\Inetpub\wwwroot\wss\VirtualDirectories\{WebAppName}{PortNumber}

So, if I created a web application called “staging”, and set it to port 80, I would expect the root directory to be C:\Inetpub\wwwroot\wss\VirtualDirectories\staging80.

To start, we need to make a small modification to the web app’s web.config, found in the root directory.  We need to change the <globalization> tag to specify a couple of properties:

<globalization fileEncoding=”utf-8″ culture=”auto” uiCulture=”auto” />

By default, the “culture” and “uiCulture” properties are not included.  Setting them to “auto” allows the server to decide which cultural settings to serve up.  As you will see below we will end up overriding this at the page level, so this setting may be unnecessary in some cases.

Next, we need to create the resource files themselves.  Unlink in previous versions of .NET, the resource files in .NET 2.0 are not (or at least, do not HAVE to be) compiled into the assembly.  They remain (more or less) human readable text files on the server.  For a SharePoint web app, these files are located in the App_GlobalResources folder below the root directory.  They follow the same structure that they would for a straight-ASP.NET application (please refer to the links above for more information on these formats, or take a look at the RESX files already in the App_GlobalResources folder as examples).

I’ll assume that I have created MyApp.resx (the default), MyApp.en-US.resx (for US English), and MyApp.fr-CA.resx (for Canadian French).  Our next step is to get the SharePoint pages themselves to recognize and use them.

You can reference the resources in both master pages and page layouts.  The specific phrase used is determined by either the <globalization> tag in the web.config file, or by the page layout’s @Page directive.  The latter overrides the former.

The @Page directive has two properties that can be set to specify the language and locale to be used on that page, and they are the same properties that are specified in the web.config <globalization> tag: “culture” and “uiCulture”.  Any resources referenced on that page will be pulled from the RESX file that corresponds to these settings.  Any resources referenced in the master page will use the current page layout’s settings as well (the @Master directive does not directly set these properties).

Why would you want to hard-code these values into the page layout?  That’s where SharePoint’s variation mechanism comes into play.  When you set up variations, SharePoint creates a parallel site to your variation source.  SharePoint manages the variations through differing URLs.  For example, www.mysite.com/en, www.mysite.com/fr, and www.mysite.com/de.  Any time a page is published in the source variation site, a copy is made to the destination variation sites.  The idea is that a bi-lingual content author will then translate the source content to the destination language, and publish the page again.

SharePoint allows you to create your own master pages and page layouts, and each site (potentially) can use a separate set.  That means that if you have an English-US site, and a French Canadian site, you can create English and French master pages and page layouts, and customize each one to their respective language and locale.  If you hardcode the “culture” and “uiCulture” properties of each variation site’s pages, you can present a new localized version of your site by simply changing a portion of the URL.

This post explored the details involved in using ASP.NET 2.0 resource files to localize your application.  In my next post, I’ll talk about a few of the additional snags with this technique.

Advertisements

February 26, 2007 - Posted by | MOSS

Sorry, the comment form is closed at this time.

%d bloggers like this: