.NET MAUI Localization
Localize a .NET MAUI application once for Android, iOS, macOS, and Windows: keep the strings in .resx files, translate them in Soluling, and let the .NET build compile the localized files into satellite assemblies for every platform.
.NET MAUI uses the standard .NET localization, so the work is in the strings: XAML is compiled into the application, and its texts must come from resources. Translate in Soluling Desktop, or upload the .resx files to Soluling Cloud directly. The examples come from Soluling's MAUI Simple sample.
Simple.csproj and writes the localized .resx files next to the original. The .NET build compiles them for every target platform.- Input
- The project (
.csproj), or the resource files (.resx) themselves - Output
- Localized
.resxfiles (AppResources.fi.resx); the .NET build creates the satellite assemblies - Runtime
- The device's language, or the language you set before the pages are created
- Cloud
- Upload the
.resxfiles to Soluling Cloud directly; no desktop step needed
On this page
- Tutorial: localize a .NET MAUI application step by step
- How .NET MAUI localization works
- Configure the platforms
- Choose the language
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- The Simple sample
- FAQ
Localize a .NET MAUI application, step by step
Six steps take the application from hard-coded English to an application for every language and platform.
Prepare: move every string into a .resx file
.NET MAUI compiles the XAML into the application, so there is no XAML resource that a localized version could replace. Every text must come from a .resx file:
-
Add a resource file. Add
Resources\Strings\AppResources.resx, and set its Access Modifier to Public, so Visual Studio generates a publicAppResourcesclass for XAML. Give each string a descriptive name and a comment for the translator. You create only the original file; Soluling creates the localized ones. -
Tell .NET the original language. Add
<NeutralLanguage>en</NeutralLanguage>to the project file. -
Use the strings in XAML with
x:Static. Add an XML namespace for the resource class and replace every text the user sees or hears:Text,Title,Placeholder, and the screen reader'sSemanticProperties.DescriptionandSemanticProperties.Hint. -
Use the strings in code with format strings. Use
String.Format(AppResources.ClickedPlural, count)instead of concatenation, so the translator can reorder the words.
SemanticProperties.Hint.Add: create a Soluling project
Drag and drop the project file (.csproj) on Soluling. Project Wizard starts.
- On the Resources page, keep .resx checked. XAML is not offered in a .NET MAUI project, because localized XAML would have no effect.
- If there are existing localized
.resxfiles, Soluling imports their translations. - On the Select Languages page, add the target languages, and click Finish.
You can also add only the .resx files, or upload them to Soluling Cloud directly: the .NET build does the rest.
Translate: the strings and their comments
Each .resx file is a node in the project tree, and the grid shows its strings with the comments you wrote. Placeholders such as {0} are protected: the translator moves them but doesn't change them.
- 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 .resx files
Choose Home | Build All. Soluling writes the localized .resx files next to the original, such as Resources\Strings\AppResources.fi.resx. Then build the application in Visual Studio or with dotnet build: the .NET build includes the localized files and creates a satellite assembly, such as fi\Simple.resources.dll, for every target platform.
Soluling doesn't compile the satellite assemblies of a .NET MAUI project itself, because each target platform has its own output folder; the Compile method on the satellite assembly options sheet is None.
Update: translate only what changed
When you add or change strings, edit the original .resx file in Visual Studio, open the Soluling project, and click Home | Scan. Soluling keeps the existing translations, and you translate only the strings that were added or changed. Then build again. You can run the scan and build steps in your build pipeline with SoluMake, or with Soluling Cloud and SoluCLI.
One set of resource files for every platform
The strings are compiled into the main assembly in the original language, and each localized .resx file into a satellite assembly. At runtime, .NET loads the strings of the current UI culture, and falls back to the parent culture (fi for fi-FI) and finally to the original strings. The same resource files work on Android, iOS, macOS, and Windows, so you translate once.
x:Static reads the strings when a page is created, so a page shows the language that was active at that moment.
Configure the platforms
-
iOS and Mac Catalyst: list the languages in
CFBundleLocalizationsof theInfo.plistfiles inPlatforms\iOSandPlatforms\MacCatalyst. Otherwise the operating system doesn't use the localized resources. -
Windows: make sure that
Platforms\Windows\Package.appxmanifesthas<Resource Language="x-generate" />. - Android: no changes are needed.
<key>CFBundleLocalizations</key>
<array>
<string>en</string>
<string>fi</string>
</array>
Choose the language
By default, the application uses the device's language if its strings exist, and the original strings otherwise. To let the user choose, set the UI culture before the pages are created, for example, in the constructor of the App class:
public App()
{
// In a real application, read the language the user selected from the settings
var culture = new CultureInfo("fi");
CultureInfo.DefaultThreadCurrentUICulture = culture;
CultureInfo.CurrentUICulture = culture;
InitializeComponent();
}
Pages that already exist keep their language. To change it while the application runs, create the pages again, for example, with Windows[0].Page = new AppShell();, or ask the user to restart the application.
Translate in Soluling Cloud
With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:
- Resource files (
.resx). On the dashboard, add a project, selectResources\Strings\AppResources.resx, and choose .NET resource file (.resx) as the source type. Translators work in Translate; click Build localized files, downloadAppResources.fi.resxand the others next to the original, and build. Because the .NET build creates the satellite assemblies, this is all a .NET MAUI application needs. -
Project files (
.csproj). A project file refers to other files. 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
- Move every text the user sees or hears into a
.resxfile, including screen reader texts. - Set the Access Modifier of the resource file to Public.
- Write a comment for every string, and describe its placeholders.
- Use
String.Formatwith placeholders instead of concatenation. - List the languages in
CFBundleLocalizationsfor iOS and Mac Catalyst. - Pseudo-translate before the first real translation.
Don't
- Leave texts in XAML; .NET MAUI compiles them into the application.
- Create the localized
.resxfiles by hand; Soluling creates them. - Move values that are not text, such as colors and sizes, into the resource file unless they depend on the language.
- Rename resource strings without a reason; renamed rows lose their translations.
- Expect open pages to change language by themselves; create them again.
Typical localizability problems
See also internationalization and pseudo translation.
| Problem | How it shows | Find and fix |
|---|---|---|
| Texts in XAML | English text in a pseudo-translated build | Move them to the .resx file and use x:Static. |
| Screen reader texts in XAML | The screen reader speaks English | Move SemanticProperties texts to the .resx file too. |
| Sentences built from pieces | Word order is wrong in the translation | Use one string with placeholders. |
| Strings without comments | Translators guess the context | Write a comment for every string in the resource editor. |
| Fixed sizes | Clipped text in the pseudo or German build | Let the layout grow with the text. |
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The iOS or Mac Catalyst application stays in English | The language is not in CFBundleLocalizations |
Add the languages to the Info.plist files. |
| XAML can't find the resource strings | The resource class is not public, or the XML namespace is wrong | Set the Access Modifier to Public, and use the root namespace plus the folder, such as Simple.Resources.Strings. |
| The page doesn't change language | x:Static read the strings when the page was created |
Create the pages again, or restart the application. |
| Satellite assemblies are missing | The localized .resx files are not next to the original |
Build in Soluling, or save the downloaded files next to the original, and build again. |
| A language shows the original strings | The language is neither the device's nor the one you set | Set CultureInfo.DefaultThreadCurrentUICulture before the pages are created. |
The Simple sample
The sample is in Samples\MAUI\Simple of the Soluling installation and on GitHub. It is the .NET MAUI template application with its strings in Resources\Strings\AppResources.resx, a Finnish translation, and a Soluling project. It targets Android, iOS, Mac Catalyst, and Windows.
See .NET MAUI localization in the Desktop documentation for all the details.
FAQ
.resx file and use them with x:Static..resx files to Soluling Cloud, translate, and download the localized files; the .NET build creates the satellite assemblies. See Translate in Soluling Cloud..resx files are compiled for Android, iOS, macOS, and Windows, so you translate them once..resx files. When you create the project, Soluling imports the translations of the existing localized .resx files.Related
- .NET MAUI localization - the full Desktop documentation
- .NET localization - resource files and satellite assemblies
- Soluling Cloud - translating in a browser
- Supported formats - everything else Soluling localizes