MozNET Tutorial - Using MozStringBundleService To Localize Your Application UI

This simple tutorial will get you started with using the new MozStringBundleService to make localizing your application dead easy.
By the end of the tut, you'll be able to quickly start using the new class to make your program more language aware.
The class was first written for MozNET's internal use but, I when I started using it for the context menu a little light bulb light up in my head and it was like "Hey! This could be used to localize the host app too!" so, here we are ;)

Let's get started..

First off we need to create two files. The first one is the empty jar file and the second is a manifest with the same name that you give to your empty jar file. To create your jar file just make an empty zip file - make sure its a zip file, rar/7z won't work. Once you have your empty zip file rename it to have a jar extension instead of zip. Now you have a jar file and WinRAR/WinZip will both read/write to it.

Inside your new jar file you should add a folder or two, just to give it some structure, a good idea would be similar to: MyJar.jar -> locale -> en-US (of course you'll want to use whatever language code fits your language) Inside your language directory (en-US in the example above) you need to create the properties sheet containing the strings for your application. In the MozNET example application I named the properties sheet MozExLocale.properties. You can use any text editor to create your properties sheet. Once you're done just save the file with the .properties file extension and drag-drop it into your language folder in the jar. A simple rundown of how the properties sheet works is as follows:

#This is a comment line because it starts with a '#'
#The strings for your application are two-part here, separated by an '=' sign.
#Strings on the left-hand side of the '=' are short-hand versions that will be used internally, by your application.
#Strings on the right-hand side of the '=' are long-hand versions that will be displayed by your application, these are also the 
#strings which can be translated to create a localized version of your program. An example is on the next line.
ShrtStrgVal=Short string value
AthrStrgVal=Another string value
MyAppTtl=My Application Title
File=File
Opn=Open
Ext=Exit
    

Before we can get on with any code examples we need to discuss the manifest file. This file is what describes, to XulRunner, your file. Depending on the complexity of your jar file it can be as simple as one line to register it with XulRunner:

locale    myApp   en-US         jar:myapp.jar!/locale/en-US/
    

A description of the line above.. locale means that we're registering a properties sheet, myApp is a custom 'class' (can be anything you want) that 'separates' our jars from others, en-US is the language code we're using (your code for your translation), the final bit of the line states what jar file XulRunner should register and the directory our properties sheet is in. You'll want to change this to match your jar file, of course. Make sure the name of your jar file and the name of the manifest are the same. E.g. mozex.jar and mozex.manifest. Both of these files should be placed in the Chrome directory under your XulRunner runtime used by your program.

Now that you have an idea of how the properties sheet is put together we can start using it in our application. In the class which you want to display strings from the properties sheet (you can have more than one!) create a string variable as such..

//This gives us a permanent pointer to the location of the properties sheet, in the jar, that we registered with XulRunner.
private static readonly string MyStringBundlePath = "chrome://myapp/locale/my-LC/myAppProps.properties";
    

Now, since we want to be as efficient as possible here we need to grab our strings in a bundle, MozStringBundle, and cache it.

//First, lets create a backing field. This is actually our cache.
static MozStringBundle _MyAppStrings = null;
//Now, lets create a property that allows us easy access to the cache..
static MozStringBundle MyAppStrings
{
    get
    {
        if(_MyAppStrings == null)
            _MyAppStrings = MozStringBundleService.GetStringBundle(MyStringBundlePath);
        return _MyAppStrings; //return our backing field so we're not retrieving the bundle everytime we access this property
    }
}
    

Now, because this could lead to a lot of typing we'll want another little helper method to get strings from our bundle..

//This little helper saves a bit of typing
string GetLangString(string val)
{
    if(!string.IsNullOrEmpty(val))
        return MyAppStrings.GetStringFromName(val);
    return null;
}
    

OK, presumably you already have a bunch of elements that contain strings displayed in the UI. If you are using WPF you can bind to the properties below. In Winforms, you can write a method that assigns the properties to your controls' text properties.

string _fileHeader;
public string FileHeader
{
    get { return _fileHeader != null ? _fileHeader : _fileHeader = GetLangString("File"); }
}

string _openHeader;
public string OpenHeader
{
    get { return _openHeader != null ? _openHeader : _openHeader = GetLangString("Opn"); }
}

string _exitHeader;
public string ExitHeader
{
    get { return _exitHeader != null ? _exitHeader : _exitHeader = GetLangString("Ext"); }
}
    

Notice that the strings used in the calls to GetLangString are the ones used in our properties file on the left side of the '=' sign. This is how we pull the translation up using the MozStringBundleService and the MozStringBundle class.

Aside from not showing how the above properties would be binded in WPF (not in the scope of this tutorial), you should be able to get this up and running in your own application with a minimum amount of trouble.