.NET Localization, Part 2: Creating Satellite Assemblies

by Satya Komatineni
10/14/2002

One time in .NET that you need to know about satellite assemblies is when you are dealing with localization. For localizing text, one doesn't hard code text on a page, but uses a key for that text. The text equivalent for the key is retrieved from a file called a resource file. A resource file is essentially a dictionary of associations between the keys and their textual values. You will have this resource file duplicated once for each language that you support. .NET will retrieve values from these multiple language-resource files based on the chosen language context.

Consider a resource file called MyText.resx. A resource file can be in any of three different formats: plain text, XML, or a binary resources file. There are utilities (resgen.exe) that can convert a resource file from one format to the other. Typically, this resource file, MyTest.resx, is called a default resource because it is this resource file that the .NET libraries will go for, if there are no language-specific resource files. This file gets compiled and becomes part of your executable. If you named your application MyApplication, then you will have MyApplication.exe, containing your resource MyTest.resources (Not quite, but close).

Assume for a second that you are providing a language-dependent resource file called:

MyText.en-gb.resx

(Where en-gb stands for the English language version of Great Britain.)

Typically, this file is planned for, and constructed outside of, the building process that is employed for constructing MyApplication. You will have to refer to the localization resources to find out why. Anyway, .NET provides a mechanism by which you can create an assembly that contains just the compiled MyText.en-gb.resx. This assembly is called a satellite assembly because the presence of this assembly is optional and standalone.

Related Reading .NET Framework Essentials By Thuan L. Thai, Hoang Lam

So, in your localization process, you will be supplying these satellite assemblies; one each for each language. And if you go through the MSDN documenation for creating satellite assemblies, you will know that you use a tool called al.exe (Assembly Linker) to do this. When I went through this documentation and also the documentation on the Web, the following questions remained largely unanswered:

1. How can I use al.exe for multiple resource files?
2. What naming conventions should I use for the assembled resource files?
3. Can I use the Visual Studio IDE for this purpose?
4. How can I use ildasm to help me with this process?
5. Why do I need to use resgen?
6. Should I be using /embed or /link in al.exe?

In short, how should I go about, in a practical sense, using satellite assemblies in a non-trivial project (a project containing multiple resource files, one for each module, etc.)?

Why Can't I Use the Visual Studio IDE For My Resources?

You Can Create Resources

For smaller projects, this is quite doable. The process is as follows. Inside of Visual Studio IDE, you can highlight a project or a folder and add a new item of the type "assembly resource." This will create a resource file with the extension .resx. Because you are able to do this at a folder level, you can create resources at the root level of you project or at a sub-folder level. It is also clear that you can have multiple resource files in your project.

Example:

\MyText.resx
\MyModule1\MyMod1Res.resx

You Can Build the Application to Include the Resources

When you build the application after introducing the above resource files, you will see that the Visual Studio IDE has embedded these resource files into your application with the following names:

MyApplication.MyTest.Resources MyApplication.MyModule1.MyMod1.Resources

See the name change? These generated names are important, as you will have to use these generated names to access your resources. Let us follow up with an example of accessing these resources.

You Can Access Your Resources Based on Their Altered Names

ResourceManager rm = new ResourceManager (
     "MyApplication.MyText.Resources",Assembly.ExecutingAssembly());
String MyResourceTextValue = Rm.getString("MyResourceTextID");

Note: Read the included reference for a detailed discussion of how to use the resource managers.

Notice the first argument to the ResourceManager -- this is the altered name of the resource file. And it is also noteworthy that you will have to individually access your resource files. There is no single global way of accessing the resources from all of the resource files.

You Can Use Visual Studio IDE to Define Resources in Other Languages as Well

Taking your MyText.resx file and defining a language-dependent version is as easy as adding a new item under the same directory called:

MyText.en-gb.resx

Inside of this language-dependent file, you will specify your resources in Great Britain English. And when you tell Visual Studio IDE to build MyApplication, you will see that an extra directory is constructed under the bin directory, and a .dll file inside of it.

Bin\en-gb\MyApplication.resources.dll

This DLL is essentially the satellite assembly of your resources. As you add more and more languages, you will see these satellite assemblies created automatically.

What is Not Entirely Right About This Picture

This will work fine in a smaller environment where the developers are working as language translators as well. Once we introduce external language translators, it is better to remove these files (just the language-dependent ones and not the default ones) from the Visual Studio IDE environment and send them off to the language translators. Once the translations are available, we should be able to generate the satellite assemblies independently of the mainline Visual Studio IDE.

This separation will increase productivity due to its separation and fewer dependencies. The whole goal of this article is to show you how to go about explaining this extenral satellite assembly generation for multiple resource files.

Pages: 1, 2

Next Page