WinUI

WinUI Localization

Localize a Windows App SDK application with WinUI 3: Soluling reads your Visual Studio project, localizes its XAML, .resw strings, images, and other resources, and writes them into the language folders that the Windows App SDK build turns into one multilingual application.

The steps are the same for C# and C++. The application picks the user's language from the Windows language settings, and falls back to your original resources when a language is missing. The examples come from Soluling's WinUI Tutorial sample.

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 Localized resources C# Driving.csproj fi fi\Resources.resw de de\Resources.resw ja ja\Resources.resw Localized resources in each language folder of 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 Localized resources C# Driving.csproj fi fi\Resources.resw de de\Resources.resw ja ja\Resources.resw Localized resources in each language folder of the project
Soluling keeps Driving.csproj and writes the localized resources next to the originals. The Windows App SDK build indexes them into one application.
Input
Visual Studio project or solution (.csproj, .sln), or XAML and resource files (.xaml, .resw)
Output
Localized resources in language folders (fi\Resources.resw, fi\MainWindow.xaml, images, ...)
Runtime
The Windows App SDK indexes every language into resources.pri and picks the user's preferred language
Other resources
Images, audio, video, XML, JSON, and text files can have a version for each language

On this page

Tutorial

Localize a WinUI application, step by step

Six steps take the application from hard-coded English to a multilingual application.

01

Prepare: make the application localizable

Internationalizing a WinUI application takes these changes:

  1. Name every XAML element that has text. Add x:Name, such as <TextBlock x:Name="text1">. Without a name, the context of the text depends on the element's position and changes when you add or remove elements before it.
  2. Move the strings from code to a .resw file. Add Resources.resw to the project, add the strings with meaningful names and comments, and read them with ResourceLoader.GetString from Microsoft.Windows.ApplicationModel.Resources.
  3. Use patterns, not pieces. Use String.Format with {0} placeholders instead of string concatenation or interpolation, so the translator can move the values. For numbers, use a plural pattern with Soluling.MultiPattern.Format from Soluling's .NET library, and tell it the language with Soluling.Language.Id.
  4. Format dates with the user's languages. Use DateTimeFormatter with GlobalizationPreferences.Languages instead of building dates from their parts.
Moving hard-coded strings to a .resw file Before, the window title and the click message are hard-coded, and the message chooses its plural form with an if statement. After, the strings come from Resources.resw through ResourceLoader, and the message is a plural pattern formatted with MultiPattern.Format. Before: Tutorial\Original\MainWindow.xaml.cs appWindow.Title = "Click Sample"; myButton.Content = count == 1 ? $"Clicked {count} time" : $"Clicked {count} times"; ✕ Stays English, English plural rules only Internationalize After: Tutorial\Localized\MainWindow.xaml.cs appWindow.Title = rl.GetString("Caption"); myButton.Content = Soluling.MultiPattern.Format(rl.GetString("ClickedTimesPlural"), count); Resources.resw and fi\Resources.resw in Soluling ClickedTimesPlural English {plural, one {Clicked {0} time} other {Clicked {0} times}} Finnish {plural, one {Klikattu {0} kerran} other {Klikattu {0} kertaa}} Japanese {plural, other {{0}クリック}} ✓ The plural forms of each language: two in Finnish, one in Japanese
rl is a ResourceLoader created by the window. Soluling's plural editor shows the forms each language needs.
02

Add: create a Soluling project

Drag and drop the Visual Studio project (.csproj) or the solution (.sln) on Soluling. This is the recommended way: Soluling scans every resource file of the project, and new resource files need no changes to the Soluling project.

  • If Soluling asks what kind of file it is, choose Windows App SDK/WinUI project file.
  • On the Resources page, select the resource types. Uncheck the ones you don't localize, such as images.
  • On the Select Languages page, add the target languages, and click Finish.

Exclude what isn't text for the user: right-click a file, such as App.xaml, to exclude it, or right-click a design-time placeholder row, such as dummy, and choose Exclude | All Rows with "dummy" original.

Project Wizard Driving.csproj is detected as a Windows App SDK/WinUI project file, goes through Project Wizard's Resources page (XAML and ResW selected, images not), and Select Languages page (Finnish, German, Japanese). Drop Driving.csproj or the .sln File type Windows App SDK/ WinUI project file ✓ Detected Resources ☑ XAML ☑ ResW ☐ Images Languages Finnish (fi) German (de) Japanese (ja)
03

Translate: XAML, strings, and plural patterns

The project tree shows each resource file of the project: Resources.resw with its strings and comments, and each XAML file with the texts of its named elements. Rows with plural patterns open in the plural editor, which shows the forms that the target language needs.

  • 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.
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 build

[Ðŕîvîñĝ Ţîɱé ___] PS ✕ [Ƒîļé __] [Ĥéļþ __] [Ðŕîvîñĝ ðîšţåñçé: ____________________] 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

⚠ Inconsistent format string Name (German) The original has {0}; the translation has no placeholder: Mein Name ist ⚠ Inconsistent pattern count ClickedTimesPlural (Japanese) Japanese has only the other plural form, but the translation has one and other.
05

Build: create the localized resources

Choose Home | Build All. Soluling writes the localized resources into a folder for each language next to the originals, such as fi\Resources.resw and fi\MainWindow.xaml. Then build the application in Visual Studio: it indexes the XAML and .resw files of the language folders into resources.pri automatically. For other localized files, such as images and text files, set the Build Action to Content.

Visual Studio may warn that there are fi resources but no en resources for the default language. You can ignore it: the original neutral resources are used for English.

Localized resource folders and the built application The project folder has the original Resources.resw and MainWindow.xaml, and fi, de, and ja folders with their localized versions. The built application contains every language in resources.pri. Project folder DIR Driving\ RES Resources.resw and MainWindow.xaml, the originals fi fi\Resources.resw and fi\MainWindow.xaml de de\Resources.resw ja ja\Resources.resw Build output DIR bin\x64\Release\ EXE Driving.exe RES resources.pri every language, indexed by the build
06

Update: translate only what changed

When the application changes, open the Soluling project and click Home | Scan. Soluling keeps the existing translations, adds the new strings, and marks the rows whose original text changed. Rows are matched by the element names and resource names, so keep them stable. Translate the new rows, build in Soluling, and build the application. You can run the scan and build steps in your build pipeline with SoluMake.

Reference

Localized resources live in language folders

Every kind of resource is localized the same way: the localized version has the same name in a language folder. If the original is Resources.resw, the German one is de\Resources.resw and the Swiss German one de-CH\Resources.resw. The Windows App SDK build indexes them all into resources.pri, and at runtime the resource manager picks the version of the user's language. So you build and deploy one application with every language.

This works for images, audio, video, XML, JSON, and text files too: Soluling lets you give each language its own version of the file. See the Samples\WinUI\Resources sample.

Resource fallback

The Windows App SDK cascades: if it doesn't find a resource in the language of the user, it uses the default language, and finally the neutral resources, your originals. So a missing translation shows in the original language instead of failing.

Resource lookup for Finnish (Finland) For Finnish (Finland), the fi-FI folder is not shipped. Caption and Sample are found in fi\Resources.resw. Today was not translated, so it comes from the original Resources.resw. UI culture: fi-FI fi-FI\ not shipped fi\Resources.resw Resources.resw original, neutral Caption – ✓ Klikkausesimerkki Sample – ✓ Tämä on esimerkki Today – not translated ✓ Today is {0}
The Finnish texts are examples; the Tutorial sample has its own translations.

Choose the language

The application uses the user's preferred languages from Settings | Time & language: to see it in Finnish, move Finnish to the top of the list and start the application again. If none of the preferred languages is localized, the original resources are used.

The plural engine needs to know the language of the resources that are in use. Store the language code in each resource file, as the Tutorial sample does with a Language string (en in the original, fi in the Finnish file), and set it when the window is created:

// MainWindow.xaml.cs in the Localized version of the Tutorial sample
private ResourceLoader rl = new ResourceLoader();
...
Soluling.Language.Id = rl.GetString("Language");

Translate in Soluling Cloud

With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:

  • Windows App SDK projects. Soluling Cloud can't read a Windows App SDK project 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

  • Give every XAML element with text an x:Name.
  • Put every string of the code into a .resw file, with a comment for the translator.
  • Use String.Format patterns and MultiPattern.Format plural patterns.
  • Format dates and numbers with the user's languages.
  • Exclude design-time placeholder texts and files that have no user-visible text.
  • Pseudo-translate before the first real translation.

Don't

  • Build sentences from pieces or with string interpolation.
  • Choose plural forms with if statements; other languages have other rules.
  • Change the Build Action of XAML and .resw files.
  • Rename elements and resource strings without a reason; renamed rows lose their translations.
  • Draw text into images unless you localize the images too.

Typical localizability problems

See also internationalization and pseudo translation.

Problem How it shows Find and fix
Strings in code English text in a pseudo-translated build Move them to Resources.resw and use ResourceLoader.GetString.
Elements without names Contexts that change when the XAML changes Add x:Name to every element with text.
Sentences built from pieces Word order and plurals are wrong in the translation Use String.Format patterns, or a plural pattern.
Dates built from parts Dates in the US format in every language Use DateTimeFormatter with the user's languages.
Design-time texts Rows like dummy that the code replaces Exclude them.

Troubleshooting

Symptom Likely cause What to do
The application stays in English The language is not first in the user's preferred languages Move it to the top in Windows language settings and restart the application.
A localized image or text file is not used Its Build Action is not Content Set the Build Action of the localized file to Content.
Visual Studio warns about missing default language resources Only the localized languages have language folders Ignore it; the neutral resources are used for the original language.
Plural forms are wrong The plural engine doesn't know the language Set Soluling.Language.Id from a resource string.
New resource files are missing The Soluling project has individual files, not the project file Add the .csproj or .sln instead.

Samples

The WinUI samples are in Samples\WinUI of the Soluling installation and on GitHub:

  • Tutorial\Original: the application before internationalization. Try this first.
  • Tutorial\Localized: internationalized and localized into Finnish.
  • Resources: localizing images, audio, XML, and text files.

See Windows App SDK localization in the Desktop documentation for all the details.

FAQ

One. The localized resources of every language are indexed into resources.pri, and the application picks the user's language at runtime.

Yes. The resources and the steps are the same for C# and C++ WinUI applications.

Yes. Soluling lets each language have its own image, audio, video, XML, JSON, or text file; set the Build Action of the localized files to Content.

The project or the solution. Soluling then finds every resource file, also the ones you add later. Adding the .xaml and .resw files one by one is possible but harder to keep up to date.

Yes. Create the project in Soluling Desktop and upload it to Soluling Cloud. See Translate in Soluling Cloud.

Related

All guides