Plugin Localization

Because FogBugz plugins are encapsulated in .NET assemblies, they can take full advantage of .NET resource files in order to manage user interface text in any number of languages.  In addition, the FogBugz CLocalizer class provides developers with hundreds of resources (each representing a term or phrase that appears in core FogBugz) automatically translated to the culture of the client browser.

UI Cultures

Modern web browsers allow users to specify the language in which they would like pages to be displayed. This setting causes requests from the browser to specify one or more UI Cultures (in order of preference), each represented in a standard abbreviated form. Here are a few examples:

When the server (of a properly localized website) handles the request, it uses this UI culture data passed from the client to prepare and send a response in the proper language. The .NET framework takes some of the pain out of this process by automating the task of mapping the client-specified UI Culture to a Resource file containing culture-specific user interface elements.

Note: The FogBugz "User Options" page allows authenticated users to make FogBugz ignore the client culture and force a specific language setting. By default, this is not enabled, and the setting reads "use browser format."

Resource Files

Resource (.resx) files allow authors of .NET assemblies to store data specific to a single culture in an XML-based format containing one or more "resources." For the purposes of localization, each of these resources repressents a UI element expressed in that culture's language.

Resource files sit alongside source code in the Visual Studio project, and are compiled along with the DLL when the assembly is built. The contents of a primary resource file, representing the default (or "fallback") culture, are embedded in the core assembly, while the contents of resource files representing other cultures are compiled into secondary DLLs that reside in a neighboring directory. These directories are usually named by culture abbreviation, so a DLL compiled from a French resource file would sit in a directory named "fr-FR."

Using Resource Files to Localize your plugin

Both the free and licensed versions of Visual Studio (2003 and above) allow developers to manage localization by including specially-named resource files in their projects. Here's a step-by-step set of instructions:

1. Create a Visual Studio project for your plugin

See the article Compiling and Installing a FogBugz Plugin for a complete step-by-step.

2. Add a core resource file to the project

Use the "Add New Item" dialog to add a "Resources File," and name it something appropriate (such as lang.resx) for our task of localization. This file will contain the default (or "fall-back") values for any resource used in the project.

3. Use the resource editor to add a resource for each element to be localized

In the solution explorer, double-click on the .resx file you just created (Just leave the .Designer.cs file alone, as it helps make "resource file magic" work behind the scenes.). You'll be presented with a tabular resource editor, in which you create one resource per row. By FogBugz convention, resources are named in all capital letters:

4. Add resource files for other supported cultures

For each culture you'd like to support, create a new .resx file with the same name as the core resource file in step 2, except with the extension changed to ".<culture abbreviation>.resx". (In our simple example, we just inlcude one french resource file named "lang.fr-FR.resx".)

Then, you can use the resource editor to add one or more of the same resources you added in step 3, with the proper french translations of course:

5. Access resources in your plugin code to localize UI elements

Once resource files are added, they can be accessed in plugin code by using the name of the core resource file:

string sHTML = String.Format("<h1>{0}, {1}!</h1>", lang.HELLO, lang.KIWI)

Through the magic of .NET, the runtime value of lang.HELLO will be:

• "Bonjour" if the client culture is "fr-FR"
• "Hello" if the client culture is anything else.

Note that you will only be able to access resources from the code if they are included in the core resource file (in this case lang.resx). This is because resources must have a "fall-back" value.

6. Compile your plugin

See the article Compiling and Installing a FogBugz Plugin for a complete step-by-step.

7. Make a .zip file and upload

To upload the localized plugin to FogBugz, create a new directory (in this example, I named it "Localization_Example"), and include in it the DLL and each resource directory generated  during compilation:

Use a compression tool (such as WinRAR) to compress this folder into a .ZIP file, and use the FogBugz "Plugins" page upload it. (The steps for uploading a FogBugz plugin are fully described in the article Compiling and Installing a FogBugz Plugin.) A sample .zip file is included at the end of this article.

The CLocalizer Class

FogCreek.FogBugz.Globalization.CLocalizer, used internally by Fog Creek Software to localize the core FogBugz application,  is exposed to plugin developers as a convenience. It contains hundreds of resources (each representing a term or phrase that appears in core FogBugz) that are automatically translated to the culture of the client browser.

For example, CLocalizer.Current.FB_CASE returns:

• "Case" if the client culture is "en-US"
• "Dossier" if the client culture is "fr-FR"

An Example

The following example uses the resources shown above to output a plugin page (generated using the IPluginPageDisplay interface) with localized content:

Compile and Install It On Your Own

Download the source files: Localization_Example.cs, lang.resx, lang.fr-FR.resx

Then follow these instructions to create a functioning plugin assembly: Compiling and Installing a FogBugz Plugin