Localizing Web Parts, Custom Controls, and Class Libraries

If you've dealt with the ResourceManager in .NET 1.x--or never touched resources altogether, moving to .NET 2.0 simplifies the process to the point where it all seems too simple. Simplicity is generally a good thing, of course, and once you understand localization in .NET 2.0 you'll probably agree there's no reason why pretty much every application shouldn't be localized from the beginning (I'm in the process of localizing and existing MOSS 2007 site, hence the sentiment just expressed).

Localization is a good thing because it:

• Allows you to refactor hard-coded strings for labels, menus, and so on out of your code and into .resx files;
• Enables your application to display a user interface relevant to users of different languages.

Localization won't translate your interface for you--that still has to be done manually.

Visual Studio 2005 now takes care of all the hard work needed to develop a fully localized app in no time at all. Firstly, it provides a convenient designer for creating resource files through which you can add strings, images, icons, and text/script files. Secondly, any .resx file added to your project are automatically compiled to a .resources file and linked to your main assembly. Finally, a resource file wrapper class is generated automatically, granting you strongly-typed access to the contents of your resource files. What more could you ask for?!?

Working with resources is really straight forward if you're writing user controls or web pages (apparently WinForms are just as straightforward but I don't know much about WinForms) because both the UserControl class and Page class both derive from System.Web.UI.TemplateControl. TemplateControl exposes the protected GetGlobalResourceObject ( ) and GetLocalResourceObject ( ) methods. When a user control or web page has a resource file available to it, you also get strongly-typed access to the file like this:

Resources.MyResourceFile.MyKey;

(where 'Resources' is some weird namespace that only comes to life when you've got .resx files in your project)

On the other hand, if you're writing web parts, custom controls, or class libraries, you're probably not deriving from TemplateControl (especially in the web part case where you class inherits WebPart). You can still add resource files to you project and use a ResourceManager to pull out the stuff you need but there's an easier way.

1. Create a new class library project; name it MyCustomWebParts or whatever you like. The name you give your project will also become the name of the assembly and be used as the default namespace for any classes you add and any classes added by Visual Studio (this last bit is really important).
2. Create a new resource file (Add new item...) named strings.resx in the root of the project (you can also place your resource files in an arbitrarily-named folder but doing so will change how the file is accessed programmatically). Add a new string with a name of labelText and a value of Hello World.
3. Create a new class that derives from
   System.Web.UI.WebControls.WebParts.WebPart; name it MyWebPart or whatever you like.
4. Add a CreateChildControls ( ) method to your class and within the method body, instatiate a new Label object and add it too the Controls collection.
5. Immediately after the Label is instantiated, set its Text property from the resource file. You do this by referencing [the default namespace for the assembly].[the name of the resource file with no extension].[the resource key name].
6. Add or update a globalization element to your web.config file and set both the culture and uiCulture attributes to auto:
   <globalization uiculture="auto" culture="auto" />
   This works on a regular ASP.NET site but MOSS doesn't automatically assign the browser's current language to the System.Threading.Thread.CurrentThread.CurrentCulture and CurrentUICulture properties so you may wish to do this yourself and forego the above web.config setting.
7. Build the project and register the web part in a .aspx page--and that's it!

namespace MyCustomWebParts
{
public class MyWebPart : WebPart
{
protected override void CreateChildControls ()
{
Controls.Clear ();
Label label = new Label ();
label.Text = MyCustomWebParts.strings.labelText;
Controls.Add (label);
}
}
}

As mentioned, adding a .resx file to your project prompts Visual Studio to generate a strongly-typed wrapper class for accessing the file; this class is created in the project's default namespace. If your web part or control is the same namespace you don't need to qualify your resource file within the MyCustomWebParts namespace--you can access it directly: strings.labelText. If you've got multiple namespaces in your project (or not) it's probably a good practice to always qualify the resource class name.

If you do drop your .resx files into a folder you'll need to modify the way you reference them:

MyCustomWebParts.MyFolder.strings.labelText;

Either way, IntelliSense will help you out as you go if everything's in the right place.

To tweak performance, you can tell ASP.NET which resources are contained in the default assembly by adding an attribute to your class library's AssemblyInfo file:

[assembly: System.Resources.NeutralResourcesLanguageAttribute ("en")]

And the end result: localized web parts, custom controls, and class libraries. Cool.

Dirty Words (Michael Hanes) - blog.mediawhole.com mailto:info@mediawole.com