Using the Localization Toolkit

© 2004 by Greg Reddick

Installing the Toolkit

The Microsoft Enterprise Localization Toolkit is a tool to make it easy to internationalize ASP.NET applications. To use the Microsoft Enterprise Localization Toolkit, first download and install it from the Microsoft Download Center . Follow all of the instructions in the setup program on how to install the toolkit. You will need some version of SQL Server available to manage the database of localized items. The instructions will tell you how to install the database.

Modifying the Project

Next, either create a new web application or modify your existing one. You will need to add the following entries into the web.config file for the web site. Note that there are some typos in the directions that come with the toolkit that are fixed here:

Change the ResourceBaseName to be the same as your project name, and change the ApplicationPath to point to the root of your project, using two backslashes for each one in the path name. See the documentation that comes with the toolkit for further information on these entries.

Add a reference to the project to LocalizationToolkit.DLL, which can be found in the c:\inetpub\wwwroot\localizationtoolkit\bin directory. Change the class in each codebehind file in the project to inherit from Microsoft.Toolkits.EnterpriseLocalization.LocalizedPage instead of the default System.Web.UI.Page. Then for each control that you want to localize, in its declaration in the aspx file, add a key attribute like this:

<asp:label id="lblFoo" key="lblFoo" runat="server">Label</asp:label>

Visual Studio will complain about not understanding this attribute, but it can be safely ignored.

In the global.asax file, modify the Application_BeginRequest event to look like this:

protected void Application_BeginRequest(Object sender, EventArgs e)
{
	System.Threading.Thread.CurrentThread.CurrentUICulture = 
		new System.Globalization.CultureInfo(
		Request.ServerVariables["HTTP_ACCEPT_LANGUAGE"].Split(',')[0]);
}

This code will cause the site to be rendered in whatever is the first language specified in the Tool Options dialog in Internet Explorer. You could do other things to allow the language to be modified.

Modifying the Database

The next step is to set up the database correctly. The database needs to know what the current version of the controls installed by the .NET framework are. Run the AddControls program that was installed by the toolkit. Set the connection string to point to the database that you installed into SQL Server. Leave the Assembly Name at System.Web, and press the Load Assembly button. This should show you all of the controls that .NET knows about from the current version of the .NET framework. Check the checkbox for each of these controls to upload the info about the control into the database.

From here, you now need to load info into the database that tells it about the application. Load the main page of the application into the browser; the url should be http://localhost/LocalizationToolkit. This application has been itself internationalize, which means it has some additional functionalty for presenting the interface in several languages. Click on the hyperlink for Applications on the left, the press the button to add a new Application. Click the Edit hyperlink. Change the name to the name of your application, give it some description, give the base name as the same as your application. Press the Update hyperlink.

Click the Edit Cultures hyperlink, and add the cultures that you want to localize your language into. The cultures that are available are defined by RFC3066. This is made up of two parts: a two letter language code specified by ISO 639, optionally followed by a hyphen followed by a country code specified by ISO 3166. The dialog shows English versions of these codes.

In the upper right, select the Application you just created from the dropdown listbox. Then click the Designer hyperlink.

In the designer section, you need to add an entried for each control that you gave a key attribute to inside your application. After you have added a key and pressed update, you can then modify the properties for the key. In the properties, you need to specify what kind of control that key applies to, then press New Property. Edit the property to modify what property of the control that you want to localize. In this dialog, you are specifying the Language Neutral value for the property should a value not be available in some specific language. This will typically be English.

Then your translator will need to click on the Translator hyperlink. For each key that you created in the previous step, you will need to internationalize it into the other cultures that you have specified.

Generating the Resource Information

The next step is to run the Generator program. This program takes the information out of the database and generates resource DLLs with the internationalization information in it. After running it, select Tools Options and set the server to (local) and the database to LocalizationToolkit. Test the connection, then press OK. Then on the Application Menu, select Open Application, select your application that you specified in the database and press Open.

Then, back on the Tools menu, select Generate Resource Files. Select the browse button and point it at the DLL of your application. This will be in the bin directory under the application root in IIS. Select Satellite Assemblies, and press the Generate Files button.

Now you have to execute a command file that the program creates in the bin directory. Using the windows explorer navigate to the bin directory. Double click on the CreateSatellites.cmd file that it created. This will generate the language specific DLLs in sub directories of the bin directory. The web site has now been localized.

How it works

Whenever a page is rendered, the global.asax will set the culture to the first language specifed in the Tools Options dialog in Internet Explorer (or the equivalent in other browsers). Then it begins to render the page. The code kicks in, and enumerates all the controls on the page using reflection. It finds controls that have a key attribute, and loads the values for the properties from the resource file.

The beauty of this scheme is that the translator only has to modify the database through the web pages and never has to touch a line of code. The pages automatically update themselves to the language preference of the web browser. The drawback is that there is a slight performance hit to using this scheme talked about in the toolkit docs, since the pages are modified on the fly on each request. This can be aleviated somewhat by using caching.