WPF Localization Guidance

WPF Localization Guidance

Rick Strahl & Michele Leroux Bustamante, June 2009

wpflocalization.codeplex.com Page 1

Contents

Localization Guidance for WPF ..................................................................................................................... 2

Localization Considerations .......................................................................................................................... 2

Unicode Support ....................................................................................................................................... 3

Preferred Culture and ResourceFallback .................................................................................................. 9

Working with Resx Resources ................................................................................................................. 10

Accessing Resources with the ResourceManager .................................................................................. 14

Using XAML Resources and LocBaml to Localize Content .......................................................................... 16

What can you localize with LocBaml? ..................................................................................................... 19

Using Resource Dictionaries for Runtime Access to XAML Resources ................................................... 20

Localizing with LocBaml .............................................................................................................................. 23

Enabling Localization in your Visual Studio Project ................................................................................ 25

Run MsBuild to generate unique Uid’s for each UI element in your XAML ............................................ 29

Using LocBaml to Export Resources into a CSV file ................................................................................ 30

Binding to Strongly-Typed Resx Resources ............................................................................................. 40

Organizing Static Resx Resources............................................................................................................ 42

Things to Consider with x:Static Resource Bindings ............................................................................... 44

WPF Localization Guidance

Rick Strahl & Michele Leroux Bustamante, June 2009

wpflocalization.codeplex.com Page 2

Custom Markup Extensions for Resx Resources ......................................................................................... 46

How the Custom Markup Extension Works ............................................................................................ 50

Attached Property Binding .......................................................................................................................... 55

Other Topics of Interest .............................................................................................................................. 60

Use Autosizing for Elements ................................................................................................................... 60

Right To Left Display ............................................................................................................................... 61

Switching Languages on the Fly .............................................................................................................. 62

Application localization is not a trivial task for any type of application scenario. The process is based on a

few core principles that apply to WPF as they do to any other type of client application with a user

interface. It is important for developers to understand the basic concepts of regional data display,

locale-specific user interface customization and how to serve localized resources in both static and

dynamic fashion. These concepts are very similar for most client applications but the actual process of

localizing the static user interface components tends to vary between environments and WPF

introduces yet another approach to resource localization for XAML resources.

This whitepaper will start with a quick review of general localization considerations for completeness,

discuss how the .NET Framework handles resources for all applications, and then focus specifically on

localization scenarios for WPF explaining some of the trade-offs within each approach.

WPF Localization Guidance

Rick Strahl & Michele Leroux Bustamante, June 2009

wpflocalization.codeplex.com Page 3

Unicode Support

Unicode support is crucial for representing the wide variety of characters of the world’s many languages

seamlessly. This may seem obvious now, but it wasn’t long before the .NET Framework was released

that ANSI character sets and codepage translations were the norm. Unicode transcends the issues of

these antiquated character set formats and their incompatibilities and provides an easy way to

represent characters from multiple languages easily in the same string without having to worry about

encoding issues.

The .NET Framework supports Unicode end-to-end – from the user interface all the way down to the

database layer. This means that today, applications needn’t do anything special to receive input, process

or save data from different languages. In WPF most of the user interface content is encoded in static

but is interpreted less efficiently for double-byte character sets. UTF-16 stores all characters

using two bytes thus is a less efficient storage format but can yield more efficient interpretation

of double-byte character sets. So, although UTF-8 will suffice for most scenarios, the latter is

usually used specifically for double-byte scenarios.

Culture Mapping

Locations are defined – at least in the context of .NET localization lingo – as a language and

country/region pair. For example en-US is for English in the United States or fr-CA for French in Canada.

The country/region can also be omitted so en and fr are valid, non-specific culture identifiers which

represent English and French without the regional code. Non-specific cultures are useful for storing

regions often have different formatting rules for things like currency or date and time. For this reason

CultureInfo class, which can be used to read the culture settings for a given locale, as well as setting a

specific locale in an application. Every thread maintains a set of culture information stored as CultureInfo

settings in CurrentCulture and CurrentUICulture properties. CurrentCulture determines behavior for

WPF Localization Guidance

Rick Strahl & Michele Leroux Bustamante, June 2009

wpflocalization.codeplex.com Page 4

formatting and parsing (as previously discussed, for things like numbers and dates) and CurrentUICulture

indicates the appropriate resources to load for the thread’s locale. From any thread you can access

CurrentCulture and CurrentUICulture from the following static members:

Thread.CurrentThread.CurrentCulture, Thread.CurrentThread.CurrentUICulture or

CultureInfo.CurrentCulture, and CultureInfo.CurrentUICulture.

The main WPF thread will always be assigned a default setting for CurrentCulture and

CurrentUICulture. You can also explicitly set these values based on user preferences (to be

discussed). An important point to note, however, is that if a WPF application spins up new

application. The idea is that the static pieces of an application – strings in labels, tooltips, menu items,

headers, static messages and any other user interface content – are stored in such a way that they can

be translated separately from the immediate user interface. The generally accepted approach for this is

to provide a mechanism to extract relevant component properties as resources so that they can be

stored and localized separate from the user interface with a copy for each supported culture. Resources

are then applied to their respective component properties at runtime based on the current UI culture.

An important benefit to this approach is that a single code-based is used for the application, and that

future localizations to support new cultures should not impact the compiled code.

In WPF development there are two main approaches to resource localization: XAML-based and Resx-

based.

for each specific culture. Finally LocBaml can be used to merge and compile the localized resources into

culture specific satellite assemblies (or binary resources). This approach is purely static resulting in

compiled XAML (BAML) resources for each supported culture, where each culture-specific BAML

resource contains the entire set of localized resource values. The approach is efficient but completely

static and there is no way to interact with the way that resources are individually loaded. LocBaml is a

WPF Localization Guidance

Rick Strahl & Michele Leroux Bustamante, June 2009

wpflocalization.codeplex.com Page 5

command line tool provided by Microsoft as a utility sample application and the process of using it is

rather rigid and potentially error prone.

Resx-based resources are the traditional approach for .NET Framework application localization. They are

XML-based files that compile into binary resources and can be accessed by the application through

individual resource keys. Resx support is deeply integrated in the .NET Framework and Visual Studio,

although there’s no specific WPF experience in Visual Studio or in other XAML designers such as Blend.

Binding Resx resources to XAML elements involves using bindings and manually mapping resources to

map resources to element properties at design time.

Localizing WPF = Choices

As you can see there are a couple of different approaches available for resource localization with WPF.

The one you choose depends on the way you like to work and whether your localization process

happens once the application is complete or incrementally while you are building the application.

The LocBaml approach is a very static process and best done when the application does not change

frequently. Its big benefit is that you don’t have to do much during development to get your application

ready for localization as you can simply create XAML content in your default language and defer

localization until later. The process of using LocBaml is rigid and fairly complicated using a command line

tool that exports CSV files for the actual task of localization. Each culture has to be individually exported,