.NET MAUI Localization

Resource files (.resx)

.NET MAUI uses standard .NET resource files for localization. Each .resx file contains name/value string pairs.

File naming convention

File	Purpose
`AppResources.resx`	Default (fallback) language
`AppResources.es.resx`	Spanish (neutral)
`AppResources.fr-FR.resx`	French – France (specific)
`AppResources.zh-Hans.resx`	Chinese Simplified

Place resource files in a Resources/Strings folder or project root. The naming pattern is {BaseName}.{CultureCode}.resx.

Project configuration

Set the neutral language in .csproj so the ResourceManager resolves the default culture correctly:

<PropertyGroup>
  <NeutralLanguage>en-US</NeutralLanguage>
</PropertyGroup>

WARNING — Without NeutralLanguage set, ResourceManager may return null for default-culture lookups at runtime. Always set it.

Generated accessor class

The default .resx file auto-generates a strongly-typed class (typically AppResources) with static properties for each string key:

// Auto-generated — do not edit manually
public static string WelcomeMessage => ResourceManager.GetString("WelcomeMessage", resourceCulture);

Access strings in C#: string welcome = AppResources.WelcomeMessage;

Culture resolution order

The runtime resolves resources in this order:

Specific culture — e.g. en-US → AppResources.en-US.resx
Neutral culture — e.g. en → AppResources.en.resx
Default (fallback) — AppResources.resx

If no match is found at any level, the fallback file is used.

XAML usage

Using x:Static

<ContentPage xmlns:resx="clr-namespace:MyApp.Resources.Strings">

  <Label Text="{x:Static resx:AppResources.WelcomeMessage}" />

</ContentPage>

Using a binding with a localization service

For runtime language switching without restarting, expose resource strings through a helper that raises PropertyChanged:

public class LocalizationResourceManager : INotifyPropertyChanged
{
    public static LocalizationResourceManager Instance { get; } = new();

    public string this[string key] =>
        AppResources.ResourceManager.GetString(key, AppResources.Culture)!;

    public event PropertyChangedEventHandler? PropertyChanged;

    public void SetCulture(CultureInfo culture)
    {
        AppResources.Culture = culture;
        CultureInfo.CurrentUICulture = culture;
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(null));
    }
}

<Label Text="{Binding [WelcomeMessage], Source={x:Static local:LocalizationResourceManager.Instance}}" />

Runtime culture switching

Change the UI culture at runtime:

var culture = new CultureInfo("es");
CultureInfo.CurrentUICulture = culture;
CultureInfo.CurrentCulture = culture; // for dates/numbers
AppResources.Culture = culture;

After setting the culture, UI elements bound via x:Static will not update automatically. Use the binding approach above or navigate to a new page to pick up the change.

Platform declarations

iOS and Mac Catalyst

Add supported localizations to Platforms/iOS/Info.plist (and Platforms/MacCatalyst/Info.plist):

<key>CFBundleLocalizations</key>
<array>
  <string>en</string>
  <string>es</string>
  <string>fr</string>
</array>

Without this, iOS will not offer the app's languages in system Settings and may ignore culture overrides.

Windows

Declare supported languages in Platforms/Windows/Package.appxmanifest:

<Resources>
  <Resource Language="en-US" />
  <Resource Language="es" />
  <Resource Language="fr-FR" />
</Resources>

Android

Android picks up .resx-based localization automatically. No additional manifest entries are required.

RTL layout support

Set FlowDirection to support right-to-left languages (Arabic, Hebrew, etc.):

<!-- App-wide -->
<Application FlowDirection="RightToLeft" />

<!-- Per-page or per-element -->
<ContentPage FlowDirection="RightToLeft">
  <StackLayout FlowDirection="MatchParent">
    <Label Text="{x:Static resx:AppResources.Greeting}" />
  </StackLayout>
</ContentPage>

Detect and apply at runtime:

bool isRtl = CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft;
FlowDirection = isRtl ? FlowDirection.RightToLeft : FlowDirection.LeftToRight;

Image localization

For culture-specific images, use a naming or folder convention and select at runtime:

string cultureSuffix = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
string imageName = $"banner_{cultureSuffix}.png";
// Fall back to default if culture-specific image doesn't exist
bannerImage.Source = ImageSource.FromFile(
    FileSystem.AppPackageFileExistsAsync(imageName).Result ? imageName : "banner.png");

Alternatively, reference image paths in .resx files so each culture points to its own asset.

VS Code setup

When using VS Code (not Visual Studio), the auto-generated .Designer.cs file for .resx may not regenerate on save. Ensure DesignTimeBuild is enabled:

<PropertyGroup>
  <CoreCompileDependsOn>PrepareResources;$(CoreCompileDependsOn)</CoreCompileDependsOn>
</PropertyGroup>

Run dotnet build after adding or modifying .resx entries to regenerate the accessor class.

Quick checklist

NeutralLanguage set in .csproj
Default AppResources.resx contains all keys
Each target language has its own AppResources.{culture}.resx
iOS/Mac: CFBundleLocalizations lists all supported languages
Windows: Package.appxmanifest declares <Resource Language="..." />
RTL cultures set FlowDirection appropriately
dotnet build regenerates .Designer.cs after .resx changes

maui-localization