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