WPF Localization
Localize a WPF application without changing its code: Soluling reads the XAML and resources of your Visual Studio project or of the compiled assembly, lets you translate them with a visual preview, checks the translations, and builds a satellite assembly for each language.
Soluling supports every WPF application from .NET Framework 3.0 to the latest .NET. This guide uses the Driving sample, a small driving time calculator, and takes it from an English-only application to one that speaks Finnish, German, and Japanese and can change its language while it runs.
Driving.csproj and writes a satellite assembly, Driving.resources.dll, for each language.- Input
- Visual Studio project or solution (
.csproj,.vbproj,.sln,.slnx), assembly (.exe,.dll), or XAML and resource files (.xaml,.resx) - Output
- Satellite assemblies with the localized XAML (
fi\Driving.resources.dll), localized assemblies, or localized.xamland.resxfiles - Runtime
- .NET loads the language of the current UI culture; Soluling's library adds a runtime language switch
- Preview
- Visual preview of the windows and pages in each language
On this page
- Tutorial: localize a WPF application step by step
- How WPF localization works
- Culture fallback
- Choose and change the language
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- The Driving sample
- FAQ
Localize a WPF application, step by step
Six steps take the Driving sample from a hard-coded English application to localized satellite assemblies.
Prepare: make the application localizable
The original Driving application works, but it is not ready for localization. Its elements have no stable identifiers, and it writes its result with code like this:
hoursLabel.Content = hours + " hour(s)";
minutesLabel.Content = minutes + " minute(s)";
Internationalizing the application takes three changes:
-
Add an
x:Uidfor the assembly method and for a runtime language switch. Project localization reads the XAML files and does not need one. The assembly method and the runtime language switch do. Soluling uses thex:Uidas the context of the element's strings, so a translation stays with its element when you rearrange the XAML. Without it, the context is the element's position, such asLabel[0]. To add them automatically, runMsBuild /t:updateuid Driving.csproj. -
Move the strings from code to resources. Add them to
Properties\Resources.resxwith meaningful names, such asAbout, and useProperties.Resources.Aboutin the code. Texts in the XAML can stay where they are; Soluling localizes the XAML itself. -
Use one pattern for sentences with numbers. Don't build a sentence from pieces. The Driving sample stores the whole result as an ICU message pattern with plural forms, and formats it with
MultiPattern.FormatMultifrom Soluling's .NET library. See patterns.
_ marks the access key (Alt+D). Plural forms are simplified here.Add: create a Soluling project
Build the application in Visual Studio first; Soluling needs the compiled assemblies when it builds. Then drag and drop one of these on Soluling. Project Wizard starts.
-
The Visual Studio project or solution (
Driving.csproj,.sln). This is the recommended way. Soluling finds every.xamland.resxfile the project uses, and a solution picks up new projects automatically. -
The compiled assembly (
Driving.exe). You don't need the source code; Soluling reads the compiled XAML (BAML) from the assembly. Every element needs anx:Uid. On .NET 5 and later, add the main.dll.
Prefer the project or solution. Soluling reads the XAML files, so you don't add x:Uid attributes. The compiled assembly needs an x:Uid on every element that has text. Project and binary localization compares the two.
On the Resources page, keep the default resource types, ResX and XAML. If the application has been localized before, Soluling finds the existing localized files, such as MainWindow.fi.xaml, and imports their translations. On the Languages page, add the target languages, and click Finish.
Translate: in the grid with a visual preview
Each window and page appears in the project tree with its strings in the grid. Select a window, and the visual editor shows a preview of it in the selected language. WPF windows size their content themselves, so you don't move or resize controls; the preview shows how the layout adapts to the translations. The preview draws the standard WPF controls; 3rd party and custom controls are not shown.
- Machine translation and translation memory. Click Use Machine Translation to translate with Amazon, Claude, DeepL, Google, Microsoft, ModernMT, or MyMemory, and reuse earlier translations from translation memory and terminology.
- External translators. Send a translation package, an Excel file, or XLIFF to a translator, and import the results back. See teamwork.
- Translators in a browser. Upload the project to Soluling Cloud and let translators work in Translate.
x:Uid and the property. Keep the x:Uid values stable.Check: find problems before release
Pseudo translation. Click Translate | Pseudo Translations | Fill, build, and run the application. Pseudo translations are longer and use accented characters, so texts that don't fit and strings still in the code (shown in plain English) stand out. See pseudo translation.
Pseudo-translated Original build
Validation. Soluling validates translations while you type and in batch (Validation | Validate Translations): missing translations, inconsistent placeholders and patterns, duplicate hotkeys, and more. See validation.
Validation: German
Build: create the satellite assemblies
Choose Home | Build All. Soluling compiles the localized XAML and resources into a satellite assembly for each language, in a language folder next to the original assembly. Choose Home | Run Localized to start the application in a target language.
Compiling localized XAML needs MSBuild, so the machine that builds, including a build server that runs SoluMake, needs Visual Studio or Build Tools for Visual Studio. On the Output sheet of the source, you can instead create localized assemblies: full copies of Driving.exe with the translated resources inside.
Update: translate only what changed
When the application changes, build it in Visual Studio and click Home | Scan. Soluling compares the new XAML and resources with the project, keeps the existing translations, adds the new strings, and marks the rows whose original text changed so that their translations are checked again. Rows are matched by their context, so keep the x:Uid values and resource names stable. Translate the new rows and build again.
You can automate the scan and build steps in your build pipeline with the SoluMake command-line tool.
XAML compiles into the assembly; languages ship as satellite assemblies
When Visual Studio builds a WPF application, it compiles each .xaml file into binary XAML (BAML) and embeds it into the assembly, together with the compiled .resx resources. A satellite assembly contains the localized BAML and resources of one language. At runtime, .NET loads the resources of the current UI culture (CultureInfo.CurrentUICulture) from the matching language folder.
WPF layouts size themselves: with Grid, StackPanel, and SizeToContent, a longer translation makes its control bigger. You don't need a separate layout for each language, but avoid fixed widths and heights.
-
Data binding.
StringFormatin a binding does not use the current culture but theLanguageproperty of the element. Turn on Language property adding in Soluling, and it adds theLanguageattribute to the root of every localized XAML. -
Right-to-left languages.
FlowDirectionis a XAML property, so you translate it like any other: set it toRightToLeftin Arabic and Hebrew, and WPF mirrors the layout.
Culture fallback
.NET looks up each resource separately: first in the specific culture (fi-FI), then in its parent (fi), and finally in the neutral resources of the main assembly. So a missing translation shows in English instead of failing, and one fi folder serves every Finnish locale. Add the neutral language, such as Finnish (fi), as the target language, and add a country-specific language only when it really differs, for example de-CH.
Choose and change the language
By default, .NET uses the Windows display language. Soluling's .NET library, available as the Soluling NuGet package, adds an initial language that follows the user's locale or a saved choice, and a runtime language switch. Set the initial language in the constructor of the application, before the first window is created:
// App.xaml.cs
public partial class App : Application
{
public App()
{
Soluling.Language.SetInitial(Driving.Properties.Settings.Default.Language);
}
}
SelectLanguage.Select from the Soluling.WPF namespace shows the languages that have a satellite assembly, loads the selected language, and translates the open windows without restarting the application. It needs an x:Uid on every element. Texts set in code are not in the XAML, so set them again after the switch:
// MainWindow.xaml.cs in the Multilingual version of the Driving sample
private void languageMenu_Click(object sender, RoutedEventArgs e)
{
if (SelectLanguage.Select())
{
Properties.Settings.Default.Language = Soluling.Language.Culture.Name;
Properties.Settings.Default.Save();
// Set the texts that the code sets, such as the result, again in the new language
UpdateItems();
}
}
Translate in Soluling Cloud
With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:
- XAML and resource files (
.xaml,.resx). Upload them on the dashboard, translate, and download the localized files. You compile them into satellite assemblies yourself, which is complicated for XAML, so prefer the next way for XAML. - Visual Studio projects and assemblies. Soluling Cloud can't scan these itself. Create the project in Soluling Desktop, and choose Translate | Configure Cloud to upload it. Use Import from Cloud to get the translations back and build the localized files locally. Your application files never leave your machine.
To run the scan, upload, import, and build steps in your build pipeline, use SoluMake. See the Cloud tutorial and workflows.
Do and don't
Do
- Add an
x:Uidwhen you localize the compiled assembly or switch the language at runtime. - Let the layout size itself with
Grid,StackPanel, andSizeToContent. - Give resource strings meaningful names, and add comments for the translator.
- Store whole sentences with placeholders, and use plural patterns for numbers.
- Keep
x:Uidvalues and resource names stable after translation starts. - Pseudo-translate before the first real translation.
Don't
- Set UI text in code; it stays in the original language unless it comes from resources.
- Build sentences from pieces, such as
hours + " hour(s)". - Give controls fixed widths that only fit English.
- Move all XAML texts into
.resxfiles just for localization; Soluling localizes XAML directly. - Rename or move the satellite assemblies.
Typical localizability problems
See also internationalization and pseudo translation.
| Problem | How it shows | Find and fix |
|---|---|---|
Elements without x:Uid |
Contexts like Label[0], or strings missing with the assembly method |
Add x:Uid attributes, by hand or with MsBuild /t:updateuid. |
| Strings in code | English text in a pseudo-translated build | Move the strings to Resources.resx. |
| Sentences built from pieces | Word order and plurals are wrong in the translation | Use one string with placeholders, or a plural pattern. |
| Fixed sizes | Clipped text in the pseudo or German build | Remove fixed widths and heights, and let the layout size itself. |
| Formatted bindings | Dates and numbers in the original language's format | Turn on Language property adding. |
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Building fails | MSBuild from Visual Studio or Build Tools for Visual Studio is missing | Install Visual Studio or Build Tools for Visual Studio on the machine that builds. |
| The application stays in English | The UI culture has no matching language folder, or the satellite assemblies were not deployed | Check that fi\Driving.resources.dll is next to the main assembly, and set the language with Soluling.Language.SetInitial. |
| An element is not translated after a runtime language switch | The element has no x:Uid, or the code sets its text |
Add x:Uid, and set code-set texts again after SelectLanguage.Select. |
| The preview does not show a window | The window uses 3rd party or custom controls | Translate in the grid; the preview shows only standard WPF controls. |
| A property is not in the project | The scan rules do not include it | Check the scan rules, and add a rule for your own or 3rd party controls. |
The Driving sample
The sample is in Samples\WPF\Driving of the Soluling installation and on GitHub. It has three versions of the same application:
- Original: the English application before internationalization, with hard-coded strings and no
x:Uidattributes. - Localized: internationalized, with translations and plural patterns.
- Multilingual: as above, with a runtime language switch.
The Samples\WPF folder has many more samples, for example, data binding, right-to-left languages, and styles. See WPF localization in the Desktop documentation for all the details.
FAQ
.exe or .dll. The elements need x:Uid attributes, which you add in the source before you build..resx files.MainWindow.fi.xaml and Resources.fi.resx, and imports their translations. See migration.Related
- WPF localization - the full Desktop documentation
- .NET localization - resource files, satellite assemblies, and other .NET applications
- Runtime language change - in .NET and other platforms
- Supported formats - everything else Soluling localizes