How to: Localize an Application
This tutorial explains how to create a localized application by using the LocBaml tool.
.gif) Note: |
|---|
The LocBaml tool is not a production-ready application. It is presented as a sample that uses some of the localization APIs and illustrates how you might write a localization tool. This topic contains the following sections.
|
Introduction Section
This discussion gives you a step-by-step approach to localizing an application. First, you will prepare your application so that the text that will be translated can be extracted. After the text is translated, you will merge the translated text into a new copy of the original application.
Requirements
Over the course of this discussion, you will use Microsoft build engine (MSBuild), which is a compiler that runs from the command line.
Also, you will be instructed to use a project file. For instructions on how to use MSBuild and project files, see
Building and Deploying Windows Presentation Foundation Applications.
All the examples in this discussion use en-US (English-US) as the culture. This enables you to work through the steps of the examples without installing a different language.
Create a Sample Application
In this step, you will prepare your application for localization. In the Windows Presentation Foundation (WPF) samples, a HelloApp sample is supplied that will be used for the code examples in this discussion. If you would like to use this sample, download the Extensible Application Markup Language (XAML) files from Use LocBaml Tool.
Develop your application to the point where you want to start localization.
Specify the development language in the project file so that MSBuild generates a main assembly and a satellite assembly. The project file in the HelloApp sample is HelloApp.csproj. In that file, you will find the development language identified as follows:
<UICulture>en-US</UICulture>Add Uids to your XAML files. Uids are used to keep track of changes to files and to identify items that must be translated. To add Uids to your files, run updateuid on your project file.
msbuild /t:updateuid helloapp.csproj
To verify that you have no missing or duplicate Uids, run checkuid.
msbuild /t:checkuid helloapp.csproj
Create a DLL
The input for LocBaml must be a .baml, .resoures, or .dll file.
Compile HelloApp to create a dynamic-link library (DLL), which will be the input for the LocBaml tool. Compile as follows:
msbuild helloapp.csproj
Go to the Bin\Debug\en-US directory to find the newly created .dll (HelloApp.resources.dll). Example:C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll.
The input for the LocBaml tool is HelloApp.resources.dll.
Build the LocBaml Tool
All the files necessary to build LocBaml are located in the WPF samples. Download the C# files from the Use LocBaml Tool sample.
From the command line, run the project file (locbaml.csproj) to build the tool.
msbuild locbaml.csproj
Go to the Bin\Release directory to find the newly created executable file (locbaml.exe). Example:C:\LocBaml\Bin\Release\locbaml.exe.
The options that you can specify when you run LocBaml are as follows:
parse or -p: Parses Baml, resources, or DLL files to generate a .csv or .txt file.
generate or -g: Generates a localized binary file by using a translated file.
out or -o [filedirectory]: Output file name.
culture or -cul [culture]: Locale of output assemblies.
translation or -trans [translation.csv]: Translated or localized file.
asmpath or -asmpath: [filedirectory]: If your XAML code contains custom controls, you must supply the asmpath to the custom control assembly.
nologo: Displays no logo or copyright information.
verbose: Displays verbose mode information.
Note:If you need a list of the options when you are running the tool, type LocBaml.exe and press Enter.
Use LocBaml to Parse a File
Now that you have created the LocBaml tool, you are ready to use it to parse HelloApp.resources.dll to extract the text content that will be localized.
Use the following syntax to parse the .dll file and store the output as a .csv file.
LocBaml.exe /parse HelloApp.resources.dll /out:c:\Hello.csv.
Note:If the input file, HelloApp.resources.dll, is not in the same directory as LocBaml.exe move one of the files so that both files are in the same directory.
When you run LocBaml to parse files, the output consists of seven fields delimited by commas (.csv files) or tabs (.txt files). For example [Baml Name],[Resource Key],[Localization Category],[Readable],[Modifiable],[Comments],[Value].
The following list shows the output from parsing HelloApp.resources.dll. If there is no value for a particular field, the field will display as an empty field. For example, in the following output there are no localization comments, so the sixth field contains no text (notice the double commas). The final field Value is the text that must be translated. Notice that there is nothing to translate in the first line of output, and that the Localization Category is set to ignore.
HelloApp.g.en-US.resources:window1.baml,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;
HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Hello World
HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World
Translate the Localizable Content
Use any tool that you have available to translate the extracted content. A good way to do this is to write the resources to a .csv file and view them in Microsoft Excel, making translation changes to the last column (value).
Use LocBaml to Generate a New .resources.dll File
The content that was identified by parsing HelloApp.resources.dll with LocBaml has been translated and must be merged back into the original application. Use the generate.or -g option to generate a new .resources.dll file.
Use the following syntax to generate a new HelloApp.resources.dll file. Mark the culture as en-US (/cul:en-US). This example generates an updated en-US file; however, when you generate a .resources.dll file for your application, use the culture that you are translating to.
LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US
Note:If the input file, Hello.csv is not in the same directory as the executable, LocBaml.exe, move one of the files so that both files are in the same directory.
Replace the old HelloApp.resources.dll file in the C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll directory with your newly created HelloApp.resources.dll file.
"Hello World" and "Goodbye World" should now be translated in your application.
Some Tips for Using LocBaml
All dependent assemblies that define custom controls must be copied into the local directory of LocBaml or installed into the GAC. This is necessary because the localization API must have access to the dependent assemblies when it reads the binary XAML (BAML).
If the main assembly is signed, the generated resource dll must also be signed in order for it to be loaded.
The version of the localized resource dll needs to be synchronized with the main assembly.
What's Next
You should now have a basic understanding of how to use the LocBaml tool. You should be able to make a file that contains Uids. By using the LocBaml tool, you should be able to parse a file to extract the localizable content, and after the content is translated, you should be able to generate a .resources.dll file that merges the translated content. This topic does not include every possible detail, but you now have the knowledge necessary to use LocBaml for localizing your applications.
See Also
Concepts
Globalization for the Windows Presentation Foundation
Use Automatic Layout Overview