nternationalization of applications is something developers have been encouraged to do for years, though all-too-frequently it doesn’t get done. But the risks of not doing so are growing ever higher. The rapid maturation of the global marketplace means companies must increasingly look beyond their shores and venture into fast moving markets like China and India. Surviving in these huge markets requires localization of the applications into the native language(s). English alone won’t cut it. For example, in China, a large portion of the computing population uses applications with UIs localized in Chinese, not English.
Microsoft recognizes the importance of providing globalization and localization support for applications running on Windows?at least, it has provided a number of ways to support developers in creating localized versions, and the WPF (Windows Presentation Foundation) is no exception. In WPF, Microsoft has taken a different methodology for localization that helps address the serious concern that localization is more than just pure string translation?rather, it is about localizing the entire UI.
In this article I will take you through the steps of localizing a WPF application. I will show how you can handle formatting issues (such as date and currency) as well as how you can localize string contents in your application. For this article I will use Chinese as the target language. You can modify the application to include as many other languages as you like.
Figure 1 shows the sample application you will build in this article. The user can choose the culture he wants and upon restarting the application, the selected language will be displayed. Restarting the application is necessary to ensure that the culture is changed since changing during runtime can be unreliable.
|What You Need|
Creating the UI
To get started, I’ll first create the application using Visual Studio 2005 Beta 2. In File->New Project?, select the Avalon Application template (using Visual Basic) and name the application “WPF”. Save the project as “C:WPF”.
I will first create the left panel of the window (see Figure 2).
The following XAML code creates the controls shown in Figure 2:
|Figure 1. Choosing the Tongue: The sample application for this article allows the end user to choose the language that they would like to use. For the sample, Chinese is the only option.|
Date and Time Currency Cultures
Figure 3 shows the components on the right panel of the window.
The following XAML code creates the controls shown in Figure 3:
|Figure 4. Add the Culture: Create a new application setting and set it to en-US.|
Adding a New Application Setting
Next you will want to create a new application setting for your project so that it can be used to persist the language preference of the user. To create an application setting in your WPF application, double-click on My Project in Solution Explorer and click the Settings tab. Add the new Culture application setting as shown in Figure 4. Give it a default value of “en-US” (the default English-US culture) and set its scope to User so that each language preference is specific to individual users rather than by machine.
In the code behind of Window1.xaml (Windows1.xaml.vb), first import the following namespaces:
Imports System.GlobalizationImports System.Threading
When the form is instantiated, you first retrieve the culture preference previously saved by the user and set the current thread to the retrieved culture. Note that you set both the CurrentUICulture (for localization of UI) and the CurrentCulture (for number and date formatting, etc.) properties.
Public Sub New() Dim cultureCode As String = My.Settings.CultureThread.CurrentThread.CurrentUICulture = _ New CultureInfo(cultureCode)Thread.CurrentThread.CurrentCulture = _ New CultureInfo(cultureCode) InitializeComponent()End Sub
When the form is loaded, you first display the date and currency information through the DisplayText() subroutine (which I will define shortly). You then retrieve all the cultures supported in .NET using the GetCultures() method and programmatically add them to the combobox.
Private Sub OnLoaded( _ ByVal sender As Object, _ ByVal e As RoutedEventArgs) Handles Me.Loaded DisplayText() '---display all the cutlures in the combobox control Dim CI As CultureInfo For Each CI In System.Globalization. _ CultureInfo.GetCultures( _ CultureTypes.SpecificCultures) Dim item As New ComboBoxItem item.Content = CI.DisplayName item.Tag = CI.Name cmbCultures.Items.Add(item) NextEnd Sub
Note that the friendly name (DisplayName, e.g. “Chinese (People’s Republic of China)”) of the CultureInfo object is displayed in the combobox (see Figure 5) while the culture code (Name, e.g. “zh-CN”) is saved in the Tag property of the ComboBoxItem object.
|Figure 5. Cultures: All supported cultures are displayed in the combobox.|
When the user changes the selection in the combobox, you save the selected culture into the Culture application setting. Notice that the My namespace automatically displays the Culture application setting through Intellisense:
Public Sub SelectedIndexChanged(ByVal sender As Object, _ ByVal e As SelectionChangedEventArgs) My.Settings.Culture = cmbCultures.SelectedItem.Tag My.Settings.Save()End Sub
The DisplayText() subroutine simply displays the current time and a sample currency by using formatting parameters in the ToString() method:
Private Sub DisplayText() txtDateTime.TextContent = Now.ToString("D") Dim amount As Single = 1234.56 txtCurrency.TextContent = amount.ToString("C")End Sub
Adding Uids to XAML files
With the UI built and the code written, you now need to add Uids to all the elements in your XAML files. Uids are used to keep track of changes to files and identify items that must be translated. You can use the MSbuild.exe tool to add Uids to all your XAML elements. To invoke the MSBuild tool, go to Start->Programs->Microsoft WinFX SDK->Release Build Environment and type in the following command (see also Figure 6):
C:WPF>msbuild /t:updateuid WPF.vbproj
|Figure 6. Adding Uids: Use MSbuild to add Uids to all XAML elements.|
All the elements in your XAML files will now have the x:Uid attribute added:
Date and Time... ...
To check that all elements have the Uid attribute, you can use the following command:
C:WPF>msbuild /t:checkuid WPF.vbproj
Specifying a Language
In the project file of the current project, you need to specify the current default culture used so that when the project is built, a main assembly and a satellite assembly (for the default language) will be built.
In WPF.vbproj, add the following line in bold:
en-US Debug AnyCPU...
This specifies that the default culture used for this application is “en-US”. You can now compile the application using Build->Rebuild WPF (see Figure 7).
A WPF.resources.dll file containing all the resources used by your application will now be located in the “C:WPFinen-US” folder (see Figure 8).
Building the LocBaml Tool
Once the resources used by the application are extracted as a resource file (.resource.dll), you can easily create another resource file containing the elements of the language you are targeting (Chinese, in this example). For this task, you will make use of a tool provided by Microsoft?LocBaml (Localize Binary Application Markup Language). You can download the LocBaml tool from: http://winfx.msdn.microsoft.com/library/default.asp?url=/library/en-us/wcp_samples/html/ef1f62b2-3ab7-4fe1-9494-4bf58fadfb57.asp. The LocBaml tool is used to parse resources files and extract text elements so that they can be localized easily.
As only the source code of the tool is provided, you need to do some work in order to use the tool. Assuming that the source code of the LocBaml tool is saved in the C:LocBaml directory, the CSharp folder contains the actual source code of the LocBaml tool and the XAML folder contains a sample application for you to test the tool (we won’t be using it for this article).
In Start->Programs->Microsoft WinFX SDK->Release Build Environment, change to the directory containing the LocBaml tool project file and type (see also Figure 9):
The executable part (.exe) of the tool will now be located in C:LocBamlCSharpinDebug (see Figure 10).
Localizing the Content
To use the LocBaml tool to extract the text content from the resource file, type the following in the Release Build Environment command window:
C:LocBamlCSharpinDebug>locbaml /parse c:WPFinen-USWPF.resources.dll /out:c:WPF ext.csv
A file containing multiple columns of comma-separated fields is saved in the file named text.csv. You can double-click it to view it in Microsoft Excel (see Figure 11). This file contains all the text content (and other information) used in the application.
Each row in the file contains seven fields separated by a comma, with the following field names:
[Baml Name],[Resource Key],[Localization Category],[Readable],[Modifiable],[Comments],[Value]
In particular, to change the text content of the application, you need to modify the last field, changing its contents from English to your target lanugage. You can also use Notepad to view the Text.csv file, as I’ve done in Figure 12. It shows three lines from the file. At the end of each line, I’ve replaced the Value field with the appropriate Chinese characters; these will be displayed in the UI.
|Author’s Note: There is a variety of ways to enter Chinese characters: Windows XP includes Chinese support or you can use a third-party tool. This link offers explicit instructions on Chinese language input.|
Once you are done with the translation, save the file as Text1.csv (remember to save the file as a Unicode text file, or else you will lose the Chinese characters).
Create a new folder called “zh-CN” in C:LocalizedWPFLocalizedWPFin. This will store the localized (Chinese) resources for the application.
To generate the localized resource file from the Text1.csv file, type the following command using the LocBaml tool:
C:LocBamlCSharpinDebug>locbaml /generate c:WPFinen-USWPF.resources.dll /trans:c:WPF ext1.csv /out:c:WPFinzh-CN /cul:zh-CN
A resource file will now be saved in the C:WPFinzh-CN folder.
You can now test the application by pressing F5 in Visual Studio 2005. Change the culture to “Chinese (People’s Republic of China)” and restart the application. The right panel of the application window will display the Chinese characters (see Figure 13).
|Figure 13. Eastern Exposure: The finished application, translated to Chinese, is shown.|
The chief advantage of extracting the text content from resource files using the LocBaml tool is that it allows you to leave the translation process to the real language expert, not the programmer.
In this article, you have learnt how to localize a WPF application using the LocBaml tool. Using the LocBaml tool, you can concentrate on building your WPF application and then perform the localization at a later stage. Let me know if you encounter any issues in using the LocBaml tool.