Localization in WPF and C#

[sciguyryan]

Introduction:

So. You want to know how to build a simple localization system in C# and WPF? No problem! That is what this tutorial is for.

In this tutorial I will describe my favoured method of localization using XmlDataProvider.

What Do I Need?

All you need for this are a WPF C# project (though you are welcome to port it to other languages if you want)! That's it. I'm using a .NET 4.0 language for this but you can use others if you wish.

Step 1 - Your XML File:

First you need to add a new directory to your project, you can call it whatever you like but I called mine "languages". Next, inside this file you need to add a new item, an XML file. This will hold your language data. Here is a portion of the XML file used for CSIT:

<?xml version="1.0" encoding="utf-8"?>
<CSIT for="1.*" name="English">
  <!-- Remember. For menu items the character following the underscore (_) character will be set as the menu accelerator key. -->
  <MenuItems>
    <MenuFile Header="_File" />
    <MenuExit Header="E_xit" />
    <MenuTools Header="_Tools" />
    <MenuOptions Header="_Options..." />
    <MenuHelp Header="_Help" />
    <MenuAbout Header="_About..." />
  </MenuItems>
</CSIT>

Not to bad eh? As you can see - your standard XML file. You can use whatever layout elements you like, you do not have to use the same structure as mine.

Now. Once you are done setting up your XML file, name it something like en.xml or whatever language code you are using. Be sure to set the build action of this file to "content" and "copy if newer". This is quite important since if you set these these incorrectly the file will not get copies and updated when you build your program.

Now. The next stage is to link this file into the program so it can be used.

Stage 2 - Linking the Documents:

Thankfully XAML provides a nice easy way of representing this kind of link - a binding. Not all things can be easily bound but most things can.

You will need to add the following code to your App.xaml document - this will make localizing the whole application much simpler. The code you need is as follows:

<Application.Resources>
    <XmlDataProvider x:Key="Language" Source="/languages/en.xml" XPath="CSIT"/>
</Application.Resources>

As you can see. I added mine into the application resources - just to save adding it to each window (since my app has quite a few!).

A few things to note here, the x:Key represents the ID by which we will access this element later. The source you will need to customize to be the relative location of the XML file to your application.

Finally, the XPath attribute. You should set this to the root element in your XML document, which in my case was "CSIT".

So now. You already have the XML document and the basic linking - not bad for a start. But our work is not done yet - now we need to use the information from the XML file in the program via bindings.

Stage 3 - Data Bindings

I guess by now, if you have been using WPF and C# you already know about bindings and since this tutorial is about localization I will not dwell on it since there are probably other tutorials on here for that already. Here is an example of how I used the above binding code in my application:

<Menu IsMainMenu="True" Margin="5">
    <MenuItem>
        <MenuItem.Header>
            <AccessText Text="{Binding Source={StaticResource Language}, XPath=MenuItems/MenuFile/@Header}" />
        </MenuItem.Header>

        <MenuItem Click="MainWindowExit">
            <MenuItem.Header>
                <AccessText Text="{Binding Source={StaticResource Language}, XPath=MenuItems/MenuExit/@Header}" />
            </MenuItem.Header>
        </MenuItem>
    </MenuItem>
</Menu>

I've bolded the bits that we are interested in. These are binding references. Note that we are using the key for the XmlDataProvider that I described earlier.

The XPath is what we are interested in here - this is the path, relative to the XPath attribute designed in the main XmlDataProvider element I designed earlier. The item with the at sign (@) prefix represents an attribute which should have its value will be read. So. For the first item above, the resulting menu will show as "File". Simple eh?

Stage 4 - The Language Framework

So. We now have a language binding that works - but it's not quite there yet since we can't change languages and without that what good is a localization framework?

For this next part we will need more code - and luckily I already have the code for it written. The code is attached.

This code handles most of the work for you. If you do not want the language version compatibility code, feel free to remove it however I found it useful when working with varying program versions.

In App.xaml.cs add the following code:

/// <summary>
/// This will handle the languages and language changes.
/// </summary>
public static LanguageHandler LanguageHandler = new LanguageHandler();

... and this will handle the language changes over the whole program. In the starting windows initialization function I added the following code:

// Add a language changed listner.
App.LanguageHandler.LanguageChanged += new LanguageHandler.LanguageUpdatedHandler(UpdateLanguage);
 
// Set the language to the default - English.
try
{
    App.LanguageHandler.SetLanguageResource("en");
}
catch (Exception ex)
{
    System.Windows.MessageBox.Show("Language resource could not be set!");
    return;
}

Strictly speaking I didn't need to call this here given what I have shown you so far - however there are reasons that I will explain below.

In some occasions there may be items where you have strings that cannot be bound to directly - this is the reason for the event handler. The event handler fires when the language changes and causes a function to be run - in this case the following code:

/// <summary>
/// This will cause the special localizable strings to be updated. Those that cannot be directly bound
/// with data bindings.
/// </summary>
private void UpdateLanguage(object sender, LanguageUpdatedArgs e)
{
    this.statusBarStatus.Content = App.LanguageHandler.GetLocalizedString("StatusWelcomeString");
}

So. This can be used for any items that need to be set dynamically when the changes are made. In my application for example strings need to be checked and changed at varying places.

Just remember that if you are doing to use the language handler file I included, you will also need to change this line:

strings = languageInfoFile.Element("CSIT").Element("Strings").Elements("String");

...And include the new root element in there too or else it will not work!

Hopefully that will provide a nice introduction to localization - or at least my method of it. If anyone has any comments, suggestions or improvements feel free to share them!

Thanks for reading.