.NET MAUI

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

Download Soluling

You build C# Simple.csproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The page as it is in the project has been translated in the editor Localized resources C# Simple.csproj fi AppResources.fi.resx de AppResources.de.resx ja AppResources.ja.resx A localized AppResources.resx for each language, next to the project You build C# Simple.csproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The page as it is in the project has been translated in the editor Localized resources C# Simple.csproj fi AppResources.fi.resx de AppResources.de.resx ja AppResources.ja.resx A localized AppResources.resx for each language, next to the project
Soluling keeps 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 .resx files (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 .resx files to Soluling Cloud directly; no desktop step needed

On this page

Tutorial

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.

01

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:

  1. Add a resource file. Add Resources\Strings\AppResources.resx, and set its Access Modifier to Public, so Visual Studio generates a public AppResources class 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.
  2. Tell .NET the original language. Add <NeutralLanguage>en</NeutralLanguage> to the project file.
  3. 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's SemanticProperties.Description and SemanticProperties.Hint.
  4. Use the strings in code with format strings. Use String.Format(AppResources.ClickedPlural, count) instead of concatenation, so the translator can reorder the words.
Moving XAML texts to a .resx file Before, the label and the button have their texts in the XAML. After, they use x:Static to read the Hello and ClickMe strings of the AppResources class. The strings have Finnish translations. Before: MainPage.xaml <Label Text="Hello, World!" FontSize="32" /> <Button x:Name="CounterBtn" Text="Click me" Clicked="OnCounterClicked" /> ✕ Compiled into the app; can't be localized Internationalize After: MainPage.xaml in the Simple sample xmlns:strings="clr-namespace:Simple.Resources.Strings" <Label Text="{x:Static strings:AppResources.Hello}" FontSize="32" /> <Button x:Name="CounterBtn" Text="{x:Static strings:AppResources.ClickMe}" Clicked="OnCounterClicked" /> AppResources.resx and AppResources.fi.resx in Soluling Hello English Hello, World! Finnish Hei maailma! ClickMe English Click me Finnish Napsauta minua ✓ Translated once, used on every platform
Also move the texts that only a screen reader speaks, such as SemanticProperties.Hint.
02

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 .resx files, 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.

Project Wizard Simple.csproj goes through Project Wizard's Resources page (ResX only; XAML is not offered), Existing translations page (AppResources.fi.resx found), and Select Languages page (Finnish, German, Japanese). Drop Simple.csproj or the .resx files Resources ☑ ResX Existing translations AppResources.fi.resx ✓ Imported Languages Finnish (fi) German (de) Japanese (ja) XAML is not offered, because .NET MAUI compiles it into the application.
03

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.
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 [Ðŕîvîñĝ šþééð ___] 88 [Çåļçûļåţé ______________] [Çåļçûļåţé ______________] Driving time is 2 hours 30 minutes 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 ClickedPlural (German) The original has {0}; the translation has no placeholder: Mehrmals geklickt ⚠ Missing translation ClickMeHint (Japanese) The screen reader speaks the original text.
05

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.

Localized resource files and satellite assemblies Soluling writes AppResources.fi.resx, AppResources.de.resx, and AppResources.ja.resx next to AppResources.resx. dotnet build writes a satellite assembly for each language into the output folder of each target platform. Soluling: Build All DIR Resources\Strings\ RES AppResources.resx original, with your comments RES AppResources.fi.resx RES AppResources.de.resx RES AppResources.ja.resx .NET build: every platform DIR bin\Release\ DIR net10.0-android\fi\ Simple.resources.dll DIR net10.0-ios\fi\ DIR net10.0-maccatalyst\fi\ DIR net10.0-windows...\fi\
06

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.

Reference

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 CFBundleLocalizations of the Info.plist files in Platforms\iOS and Platforms\MacCatalyst. Otherwise the operating system doesn't use the localized resources.
  • Windows: make sure that Platforms\Windows\Package.appxmanifest has <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, select Resources\Strings\AppResources.resx, and choose .NET resource file (.resx) as the source type. Translators work in Translate; click Build localized files, download AppResources.fi.resx and 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 .resx file, 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.Format with placeholders instead of concatenation.
  • List the languages in CFBundleLocalizations for 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 .resx files 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

.NET MAUI compiles the XAML into the application, so a localized XAML file would have no effect. Move the texts into a .resx file and use them with x:Static.

No. Upload the .resx files to Soluling Cloud, translate, and download the localized files; the .NET build creates the satellite assemblies. See Translate in Soluling Cloud.

No. The same .resx files are compiled for Android, iOS, macOS, and Windows, so you translate them once.

Yes. Set the UI culture before the pages are created, and create the pages again after a change. See Choose the language.

.NET MAUI is the successor of Xamarin.Forms and uses the same .resx files. When you create the project, Soluling imports the translations of the existing localized .resx files.

Related

All guides