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.
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.priand 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
- How WinUI localization works
- Resource fallback
- Choose the language
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- Samples
- FAQ
Localize a WinUI application, step by step
Six steps take the application from hard-coded English to a multilingual application.
Prepare: make the application localizable
Internationalizing a WinUI application takes these changes:
-
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. -
Move the strings from code to a
.reswfile. AddResources.reswto the project, add the strings with meaningful names and comments, and read them withResourceLoader.GetStringfromMicrosoft.Windows.ApplicationModel.Resources. -
Use patterns, not pieces. Use
String.Formatwith{0}placeholders instead of string concatenation or interpolation, so the translator can move the values. For numbers, use a plural pattern withSoluling.MultiPattern.Formatfrom Soluling's .NET library, and tell it the language withSoluling.Language.Id. -
Format dates with the user's languages. Use
DateTimeFormatterwithGlobalizationPreferences.Languagesinstead of building dates from their parts.
rl is a ResourceLoader created by the window. Soluling's plural editor shows the forms each language needs.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.
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.
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
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
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.
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.
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.
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
.reswfile, with a comment for the translator. - Use
String.Formatpatterns andMultiPattern.Formatplural 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
ifstatements; other languages have other rules. - Change the Build Action of XAML and
.reswfiles. - 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
resources.pri, and the application picks the user's language at runtime..xaml and .resw files one by one is possible but harder to keep up to date.Related
- Windows App SDK localization - the full Desktop documentation
- UWP localization - the earlier Windows app platform
- Patterns - plurals, genders, and selects
- Supported formats - everything else Soluling localizes