WPF

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.

Download Soluling

You build C# Driving.csproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The window as it is in the project has been translated in the editor You ship EXE Driving.exe fi fi\Driving.resources.dll de de\Driving.resources.dll ja ja\Driving.resources.dll A satellite assembly for each language, built from the project You build C# Driving.csproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The window as it is in the project has been translated in the editor You ship EXE Driving.exe fi fi\Driving.resources.dll de de\Driving.resources.dll ja ja\Driving.resources.dll A satellite assembly for each language, built from the project
Soluling keeps 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 .xaml and .resx files
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

Six steps take the Driving sample from a hard-coded English application to localized satellite assemblies.

01

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:

  1. Add an x:Uid for 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 the x:Uid as 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 as Label[0]. To add them automatically, run MsBuild /t:updateuid Driving.csproj.
  2. Move the strings from code to resources. Add them to Properties\Resources.resx with meaningful names, such as About, and use Properties.Resources.About in the code. Texts in the XAML can stay where they are; Soluling localizes the XAML itself.
  3. 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.FormatMulti from Soluling's .NET library. See patterns.
Adding x:Uid and moving hard-coded strings to a resource pattern Before, the label has only x:Name and the result is built from hard-coded English strings. After, the label has an x:Uid, and the result comes from the ResultPlural resource, which has an English and a Finnish plural pattern. Before: Original\MainWindow.xaml and MainWindow.xaml.cs <Label x:Name="distanceLabel" Content="_Distance:" /> hoursLabel.Content = hours + " hour(s)"; ✕ No x:Uid; stays English, no plural forms Internationalize After: Localized\MainWindow.xaml and MainWindow.xaml.cs <Label x:Uid="distanceLabel" Content="_Distance:" /> resultLabel.Content = MultiPattern.FormatMulti(Properties.Resources.ResultPlural, hours, minutes); MainWindow.xaml and Properties\Resources.resx in Soluling distanceLabel English _Distance: Finnish _Etäisyys: ResultPlural English Driving time is{plural, one { {0} hour } other { {0} hours }}{plural, one {{0} minute} other {{0} minutes}} Finnish Ajoaika on{plural, one { {0} tunti } other { {0} tuntia }}{plural, one {{0} minuutti} other {{0} minuuttia}} ✓ XAML and resources translated together, with the plural forms of each language
The _ marks the access key (Alt+D). Plural forms are simplified here.
02

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 .xaml and .resx file 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 an x: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.

Project Wizard Driving.csproj goes through Project Wizard's Resources page (ResX and XAML selected), Existing translations page (MainWindow.fi.xaml and Resources.fi.resx found), and Languages page (Finnish, German, Japanese). Drop Driving.csproj or Driving.exe or .sln Resources ☑ ResX ☑ XAML ☐ Image, Icon, ... Existing translations MainWindow.fi.xaml Resources.fi.resx ✓ Imported Languages Finnish (fi) German (de) Japanese (ja) The Existing translations page appears only when Soluling finds localized files.
03

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.
The translation grid and the visual preview The grid lists the MainWindow strings with Finnish translations. The selected row, distanceLabel, is highlighted on the Finnish preview of the window. Grid: MainWindow Context English Finnish Main.Title Driving Time Ajoaika fileMenu.Header _File _Tiedosto distanceLabel.Content _Distance: _Etäisyys: speedLabel.Content _Speed: _Nopeus: calculateButton.Content _Calculate _Laske resultLabel (set in code) Visual preview: Finnish Ajoaika FI ✕ Tiedosto Ohje Etäisyys: 220 Nopeus: 88 Laske Ajoaika on 2 tuntia 30 minuuttia FI
The context is the element's x:Uid and the property. Keep the x:Uid values stable.
04

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

[Ðŕîvîñĝ Ţîɱé ___] PS ✕ [Ƒîļé __] [Ĥéļþ __] [Ðîšţåñçé: ______________] 220 [Šþééð: __________] 88 [Çåļçûļåţé ___] 2 hour(s) 30 minute(s) PS Too long and still English (hard-coded)

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

⚠ Inconsistent format string ResultPlural Original uses {0} in both plural forms; the translation uses {1}: ... {plural, one {{1} Minute} other {{1} Minuten}} ⚠ Duplicate hotkey _Entfernung: / _Ergebnis berechnen Both use Alt+E in the same window, so change one of them.
05

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.

Satellite assemblies and localized assemblies With satellite assemblies, bin\Release contains the unchanged Driving.exe and fi, de, and ja folders, each with Driving.resources.dll. With localized assemblies, each language folder contains a complete Driving.exe in that language. Satellite assemblies (default) DIR bin\Release\ EXE Driving.exe original, unchanged fi fi\Driving.resources.dll de de\Driving.resources.dll ja ja\Driving.resources.dll Localized assemblies (complete copies) DIR bin\Release\ EXE Driving.exe original, English fi fi\Driving.exe de de\Driving.exe ja ja\Driving.exe
Deploy the language folders as they are. If a satellite assembly is renamed or moved, .NET does not find it.
06

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.

Reference

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. StringFormat in a binding does not use the current culture but the Language property of the element. Turn on Language property adding in Soluling, and it adds the Language attribute to the root of every localized XAML.
  • Right-to-left languages. FlowDirection is a XAML property, so you translate it like any other: set it to RightToLeft in 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.

Resource lookup for the fi-FI UI culture For UI culture fi-FI, the fi-FI folder is not shipped. distanceLabel and calculateButton are found in the fi folder as Etäisyys and Laske. About was not translated, so it comes from the neutral resources in Driving.exe. UI culture: fi-FI fi-FI\ not shipped fi\Driving.resources.dll Driving.exe neutral (English) distanceLabel.Content – ✓ _Etäisyys: calculateButton.Content – ✓ _Laske About – not translated ✓ Driving time calculator

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();
  }
}
Runtime language switch The English Driving Time window, the Select Language dialog with English, Suomi, Deutsch, and Japanese, and the same window in Finnish without restarting. Driving Time EN ✕ File Help Distance: 220 Speed: 88 Calculate Driving time is 2 hours 30 minutes EN Select Language English suomi Deutsch 日本語 OK Ajoaika FI ✕ Tiedosto Ohje Etäisyys: 220 Nopeus: 88 Laske Ajoaika on 2 tuntia 30 minuuttia FI Same window, no restart

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:Uid when you localize the compiled assembly or switch the language at runtime.
  • Let the layout size itself with Grid, StackPanel, and SizeToContent.
  • Give resource strings meaningful names, and add comments for the translator.
  • Store whole sentences with placeholders, and use plural patterns for numbers.
  • Keep x:Uid values 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 .resx files 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:Uid attributes.
  • 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

No. With the assembly file method, Soluling reads the compiled XAML (BAML) and resources from the .exe or .dll. The elements need x:Uid attributes, which you add in the source before you build.

No. Soluling localizes the XAML itself, so the texts can stay in the XAML. Put only the strings that the code uses into .resx files.

Yes. Soluling's .NET library translates the open windows from the satellite assembly of the new language. See Choose and change the language and the Multilingual version of the Driving sample.

Soluling compiles the localized XAML with MSBuild, which comes with Visual Studio and Build Tools for Visual Studio. A build server that runs SoluMake needs one of them too.

Yes. When you create the project, Soluling finds existing localized files, such as MainWindow.fi.xaml and Resources.fi.resx, and imports their translations. See migration.

Related

All guides