Introduction
For developers used to the integrated, inbuilt localization support for Windows Forms applications, the Microsoft approach to localizing WPF applications using the somewhat primitive Locbaml tool can come as a shock. Some of the issues that have been identified with this approach are:
- The localization process is not integrated into the standard Visual Studio build mechanism (as it is for Windows Forms applications).
- There is no way to view or edit the localized XAML within the Visual Studio designer.
- Locbaml uses CSV files and has issues when the translated text includes commas. The use of CSV files forces translators to work with two separate mechanisms since they still have to work with standard .NET RESX files for programmatically translated strings.
- The Locbaml approach results in the complete binary XAML for the window being replicated in the satellite assemblies for each localized language. This results in much larger footprint for localized applications compared to the Windows Forms approach where only those resources that differ from the invariant culture are compiled into the satellite assemblies.
- There is no way to dynamically change the language of the application at runtime without closing and recreating windows.
The issues with the Locbaml approach have resulted in the development of a multitude of different solutions for localizing WPF applications. The following are just some of the solutions proposed:
At the risk of adding to the confusion, this article outlines another approach which builds on the strengths of some of these earlier solutions.
Background
The article Simple WPF Localization provides an effective, simple solution for localizing text resources in WPF applications. It uses a WPF Extension to get the string resources from the standard project Properties.Resources RESX file. This article takes a similar approach, and defines a RESX extension that allows WPF properties to be pulled from embedded RESX resources. The solution outlined here differs in the following ways:
- Resources can be localized using any embedded RESX file. This allows you to take a similar approach to Windows Forms localization and store the resources associated with each WPF window or control in a separate RESX file (typically named the same as the Window). This is important for projects with a large number of windows where it can become difficult to manage the large number of resources in a single file, particularly with multiple developers. It also means that your resource names only have to be unique within the window.
- Any WPF property (not just strings) can be localized using the RESX Extension. You can use it to localize images, locations, sizes, and other layout properties. The built-in support for images makes defining icons for windows, menus, and toolbars much simpler, and is worth using even if you don't want to localize them.
- The design time display culture can be selected dynamically using a notification icon in the system tray, allowing you to view and edit the localized windows in the Visual Studio designer. This is great for verifying the localized layout for a window without having to run the application.
- The RESX extension allows you to define a default fallback value for properties that is used if the associated resource cannot be loaded. This is particularly important when localizing non-text properties where returning a
null value may cause the page to fail to load.
Using the RESX Extension
Once you have downloaded the source code and built it, add a reference to the compiled assembly (Infralution.Localization.Wpf) to your project. If you are using the demo solution, then this is already done for you. You are now ready to use the ResxExtension in your own XAML.
Markup extensions allow you to define XAML property values that are evaluated by calling custom code defined by the Markup Extension. See the MSDN article Markup Extensions and XAML for more information. The ResxExtension derives from the base MarkupExtension class, and evaluates the property by retrieving the data from an embedded RESX resource. For instance, the following markup sets the Text property of a TextBlock to the "MyText" resource from the embedded RESX resource called MyApp.TestWindow:
<TextBlock Text="{Resx ResxName=MyApp.TestWindow, Key=MyText}"/>
If you haven't yet created the resource (and compiled your project), then this will be displayed in the WPF designer as #MyText, where the # highlights the fact that the resource has not yet been defined. The next step is to create the RESX file and define the resource. If the default namespace for your project is "MyApp", then you simply create a RESX file called "TestWindow.resx" and set its Build Action to "Embedded Resource". Add a string resource with the name "MyText" and recompile the project. If you now open the TestWindow XAML in the designer, you will see the string from the resource file displayed in the TextBlock.
To add a localization, simply copy the RESX file and rename it. For instance, to create a French localization, copy the RESX file to TestWindow.fr.resx and include it in your project as an embedded resource. Change the "MyText" resource to the French translation. When you recompile your project, Visual Studio will automatically create the French satellite assembly containing the French resources.
Setting the Default ResxName
Setting the ResxName property for each Resx element within a window leads to a lot of duplicated XAML. Patrick Duffy suggested a solution using attached properties which allows much concise XAML. This allows you to set the attached ResxExtension.DefaultResxName property at the top most element as shown below:
<Window ResxExtension.DefaultResxName="WpfApp.MainWindow" Language="{UICulture}">
The ResxName property can now be omitted from the Resx elements. Furthermore, if we only need to specify the Key property (which is the default property), then we can omit the parameter name leading to a very concise declaration:
<TextBlock Text="{Resx MyText}"/>
Setting the DefaultResxName using the attached property works provided you are using the Resx element within a normal FrameworkElement property. It will not work however when the Resx element is used within another MarkupExtension. In this case, you will still need to set the ResxName explicitly.
Changing the Design Time Culture
Open TestWindow.xaml in the designer again. You should notice that a new 
icon appears in your Windows desktop notification tray. This allows you to select the culture used at design time. Click on the icon and select "Other Cultures...". Select one of the French cultures from the dropdown list. The translations displayed in the designer will switch to those from the French RESX file.
In Visual Studio 2012 and 2013 Microsoft introduced a new designer that runs in a separate process (XDesProc). This same out of process designer is also used by Expression Blend. XDesProc shadow copies your assemblies into its own local directory - but unfortunately does not shadow copy the satellite resource assemblies. This meant that design time culture selection was broken. I have now implemented a workaround where the ResxExtension class constructor hooks the AssemblyResolve event and searches for the latest matching assembly. To determine the directories to search it looks through the running processes for Visual Studio hosting processes (*.vshost.exe) and searches the directory associated with the process. This means if you are using the Visual Studio designer and have the Enable the Visual Studio hosting process option checked (under Project > Debug settings) that design time culture switching will just work. If you disable the Enable the Visual Studio hosting process option or if you are using Expression Blend then you have to tell the ResxExtension where to search for satellite assemblies at design time. To do this you create a string value in following location in the registry:
HKEY_CURRENT_USER\Software\ResxExtension\AssemblyPath
Set the value to a semi-colon delimited list of directories to search. This should be the base directory containing your executable (not the culture specific sub-directory containing the satellite assemblies).
Changing the Culture Dynamically at Runtime
The culture of your application can be changed dynamically at runtime simply by setting the CultureManager.UICulture property. This sets the CurrentThread.UICulture and automatically updates all active XAML that uses the ResxExtension.
Images and Icons
The ResxExtension doesn't just work for text. It also makes it easy to use icons and images from RESX files in your XAML markup. For instance, to define the icon for a window, simply add an icon resource to the RESX file named "Window.Icon", then define the markup as follows:
<Window Icon="{Resx Window.Icon}"/>
This is so much easier than the standard way of defining WPF window icons, that you will probably want to use this even if you don't want to localize the icons. You can use the same technique for setting the icons for menus and toolbars.
Localizing Other Property Types
The ResxExtension can be used to localize properties of any type. For instance, the Margin property of a TextBlock could be defined as follows:
<TextBlock
Margin="{Resx Key=MyMargin, DefaultValue='18,0,0,71'}"/>
In this case, note that we have defined a DefaultValue attribute. This is the value used if no resource can be found and loaded. If you don't provide a DefaultValue for non-text properties, then the XAML may fail to load in the designer if the resource has not been defined yet. The resource can be defined as a simple string resource (with value "18, 0, 0, 71"), or you can define it as a fully typed value in the RESX file, e.g.:
<data name="MyMargin" type="System.Windows.Thickness, PresentationFramework">
<value>18, 0, 0, 71</value>
</data>
The latter is somewhat more work - but it does ensure that only valid values can be entered using the resource editor.
Formatting Bound Data
WPF provides the Binding element to bind a property to a data source. The Binding.StringFormat property allows you to supply a string used to format the data for display. For instance:
<Binding StringFormat="Selected Item: {0}" ElementName="_fileListBox" Path="SelectedItem"/>
To localize this, we would like to specify the StringFormat property using a Resx element. This works, provided you don't change the culture at runtime. If you change the culture then you will get an InvalidOperation exception with the message "Binding cannot be changed after it has been used". Unfortunately bindings weren't designed with dynamic updating of culture in mind. To overcome this, the ResxExtension can itself act like a binding. You simply set the binding properties (prefixed with "Binding") and the resource value is used as a format string. For instance, the binding above would become:
<Resx Key="MyFormatString" BindingElementName="_fileListBox" BindingPath="SelectedItem"/>
You can also specify a different resource which is used when the bound target is null by setting the BindingTargetNullKey property.
The ResxExtension supports formatting data from multiple data sources (similar to a MultiBinding) by nesting Resx elements. For instance:
<Resx Key="MyMultiFormatString">
<Resx BindingElementName="_fileListBox" BindingPath="Name"/>
<Resx BindingElementName="_fileListBox" BindingPath="SelectedItem"/>
</Resx>
In this case, you would define the MyMultiFormatString resource with placeholders for both data source arguments eg "Selected {0}: {1}".
UICulture Extension
The project also defines another markup extension - UICulture. This extension is used to set the Language property of a WPF window (or other elements) to the language matching the current CultureManager.UICulture. Like the RESX Extension, the UICulture extension automatically updates attached elements when the CultureManager.UICulture changes.
ResourceEnumConverter
For convenience, the project includes the ResourceEnumConverter class. This provides an easy mechanism for localizing the display text associated with enums. It is described in more detail in this article.
Hiding Window RESX Files in the Visual Studio Solution Explorer
One nice feature of Windows Forms localization is that the RESX files associated with a form or control are hidden by default. To see the RESX files, you click on the expand button next to the form or control. This means that as you add more languages, your Solution Explorer pane does not become too cluttered. You can also do this for the RESX files associated with a window XAML file by editing the Visual Studio project file and adding a DependentUpon XML node for the RESX file. E.g.:
<EmbeddedResource Include="TestWindow.resx">
<DependentUpon>TestWindow.xaml</DependentUpon>
<SubType>Designer</SubType>
</EmbeddedResource>
Implementation Notes
This section provides some notes on the internal implementation of the ResxExtension class. You don't need to read this to use the ResxExtension, but if you are interested in some of the design choices, then read on.
Object Lifetime Management
Object lifetime management is one of the main issues when designing a MarkupExtension that will dynamically update the XAML that uses it. The ResxExtension needs to maintain a reference to the target XAML elements that use it to enable the elements to be updated when the CultureManager.UICulture is changed. If this reference is a strong reference however, then the WPF elements that use the extension will never be garbage collected. To avoid this situation, the extension instead maintains a weak reference to the WPF target objects. This enables the target objects to be garbage collected. The only problem is that there is still a strong reference to the extension objects themselves (since we need to hold a collection of the extension objects in order to update them). This issue is overcome by periodically calling a cleanup function that removes extensions that no longer have active targets. The cleanup is triggered after a set number of extension objects have been created since the last cleanup. This lifetime management mechanism has been implemented in some base classes to enable it to be used for any MarkupExtension that requires this behaviour. The ManagedMarkupExtension provides the base class for the extension, and implements the weak reference to the WPF target objects. The MarkupExtensionManager class manages a collection of ManagedMarkupExtension
objects, and implements the update and cleanup mechanism. The ResxExtension and UICultureExtension both derive from ManagedMarkupExtension, and use a static instance of the MarkupExtensionManager class to handle updating WPF targets when the CultureManager.UICulture is changed.
Data Binding Support
Overcoming the immutability of the standard Binding markup extension proved to be quite difficult and I tried quite a few approaches before finally settling on the current design which I think is quite elegant. The solution allows you to set binding properties directly on a Resx element. The ResxExtension just delegates these properties to an underlying Binding instance and sets the Binding.StringFormat to the resource value. When the culture is changed, the ResxExtension creates a new copy of the binding and updates the target to use the new binding.
Globalizer.NET Support
The ResxExtension was designed to support localizing WPF applications using Infralution's Globalizer.NET tool (although you certainly don't need Globalizer.NET to use the ResxExtension). The ResxExtension class includes a static GetResource event that allows Globalizer.NET (or any other localization tool) to hook into the resource translation mechanism and dynamically provide translations for resources. This enables Globalizer.NET to display translated previews of windows and controls that use the ResxExtension without having to first compile the satellite assemblies. Globalizer.NET also includes the ability to scan existing WPF projects for localizable properties and automatically convert them to use the ResxExtension.
History
- 2009.04.08
- 2009.04.20
- Fixed bug in
ResxExtension.ConvertValue
- 2009.09.22
- Fixed
ResxExtension.GetDefaultValue to handle non-dependency types and added UpdateTarget methods
- 2010.01.05
- Fixed
ManagedMarkupExtension.UpdateTarget to handle targets which don’t inherit from FrameworkElement
- 2010.06.30
- Fixed issue with using
ResxExtension with PRISM
- 2011.05.30
- Fixed issue with using
ResxExtension in templates
- 2012.02.06
- Added
ResxExtension.ResxName attached property to allow setting the default ResxName for a window/control
- Added binding properties to
ResxExtension to allow you to format bound data using a resource string
- Added support for binding to multiple data sources (similar to
MultiBinding) by nesting ResxExtension elements
- Changed
ResourceEnumConverter to implement IValueConverter to allow derived classes to be used in XAML as binding converters
- Added check for dynamic assemblies in
HasEmbeddedResx to avoid exceptions being thrown internally
- 2012.03.02
- Changed name of attached property from
ResxExtension.ResxName to ResxExtension.DefaultResxName. This fixes a runtime markup parsing exception in .NET 4 if you explicitly set the ResxName parameter for an extension (see discussion regarding this bug in comments).
- 2012.03.22
- Fixed exception when changing cultures if the the
ResxExtension is used in a template
- Fixed display of culture names at design time when using in .NET 4 projects (previously the culture code was displayed rather than the friendly name)
- Add overridable
GetResourceName method to ResourceEnumConverter class to allow derived classes to change the default resource naming
- 2013.02.14
- Fixed exception when using
ResourceEnumConverter inside a multibinding ResxExtension with .NET 4 Framework
- 2014.02.20
- Fixed issue with design time culture selection not working in Visual Studio 2012, 2013 and Expression Blend
- Fixed Notification Tray icon so that it is removed when the Visual Studio project is closed
- 2015.11.30
- Added description of
BindingTargetNullKey property to allow you to specify a different resource to use when the bound target value is null.
- 2016.02.10
- Fixed example code for
DefaultResxName attached property.
