/maui-localization

name: maui-localization
description: >-
  Guidance for localizing .NET MAUI apps: multi-language support via .resx resource files,
  culture resolution and runtime switching, RTL layout, platform language declarations
  (iOS/Mac Catalyst Info.plist, Windows Package.appxmanifest), and image localization strategies.
  USE FOR: "localization", "multi-language", "resx resource", "translate app", "RTL layout",
  "culture switching", "localize strings", "right-to-left", "language support MAUI",
  "Info.plist languages".
  DO NOT USE FOR: theming or visual styles (use maui-theming), accessibility labels
  (use maui-accessibility), or content from REST APIs (use maui-rest-api).

.NET MAUI Localization

Common gotchas

| Issue | Fix | |---|---| | `ResourceManager` returns `null` for default culture | Set `<NeutralLanguage>en-US</NeutralLanguage>` in `.csproj` | | iOS ignores culture overrides | `CFBundleLocalizations` missing from `Info.plist` | | Windows doesn't show correct language | `<Resource Language="..." />` missing from `Package.appxmanifest` | | `x:Static` bindings don't update on language switch | `x:Static` is one-time — use binding approach with `INotifyPropertyChanged` | | `.Designer.cs` not regenerating in VS Code | Add `<CoreCompileDependsOn>PrepareResources;$(CoreCompileDependsOn)</CoreCompileDependsOn>` and run `dotnet build` |

⚠️ NeutralLanguage is mandatory

<!-- ✅ Always set in .csproj -->
<PropertyGroup>
  <NeutralLanguage>en-US</NeutralLanguage>
</PropertyGroup>

<!-- ❌ Missing this causes ResourceManager to return null at runtime -->

Platform declarations — don't forget these

iOS / Mac Catalyst

⚠️ Without this, iOS won't offer your app's languages in system Settings:

<!-- Platforms/iOS/Info.plist AND Platforms/MacCatalyst/Info.plist -->
<key>CFBundleLocalizations</key>
<array>
  <string>en</string>
  <string>es</string>
  <string>fr</string>
</array>

Windows

<!-- 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 required. ✅

Runtime language switching — x:Static trap

<!-- ❌ Won't update when language changes at runtime -->
<Label Text="{x:Static resx:AppResources.WelcomeMessage}" />

<!-- ✅ Updates dynamically via INotifyPropertyChanged -->
<Label Text="{Binding [WelcomeMessage], Source={x:Static local:LocalizationResourceManager.Instance}}" />

When switching culture, set **all three** properties or formatting is inconsistent:

// ✅ Complete culture switch
var culture = new CultureInfo("es");
CultureInfo.CurrentUICulture = culture;  // resource lookup
CultureInfo.CurrentCulture = culture;     // dates/numbers
AppResources.Culture = culture;           // ResourceManager

// ❌ Only sets UI culture — dates/numbers stay in old culture
CultureInfo.CurrentUICulture = new CultureInfo("es");

RTL layout — set FlowDirection at page level

<!-- ✅ Page-level — children inherit -->
<ContentPage FlowDirection="RightToLeft">
  <StackLayout FlowDirection="MatchParent" />
</ContentPage>

<!-- ❌ Only on child — parent still LTR, layout breaks -->
<ContentPage>
  <StackLayout FlowDirection="RightToLeft" />
</ContentPage>

VS Code pitfall

⚠️ `.Designer.cs` may not regenerate on save. Add to `.csproj` and run `dotnet build` after `.resx` changes:

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

Decision framework

| Need | Approach | |---|---| | Static multilingual strings | `.resx` files with `x:Static` bindings | | Runtime language switching | `LocalizationResourceManager` with `INotifyPropertyChanged` bindings | | Culture-specific images | Name images `banner_{culture}.png` or store paths in `.resx` | | RTL support | Set `FlowDirection` at page level, detect with `TextInfo.IsRightToLeft` | | Date/number formatting | Set `CultureInfo.CurrentCulture` alongside `CurrentUICulture` |

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` at page/app level
• [ ] Runtime switching sets all three: `CurrentUICulture`, `CurrentCulture`, `AppResources.Culture`
• [ ] `dotnet build` regenerates `.Designer.cs` after `.resx` changes