maui-localization

.NET MAUI 本地化

常见问题

问题	解决方法
ResourceManager 对默认区域性返回 null	在 .csproj 中设置 <NeutralLanguage>en-US</NeutralLanguage>
iOS 忽略区域性覆盖设置	Info.plist 中缺少 CFBundleLocalizations
Windows 未显示正确的语言	Package.appxmanifest 中缺少 <Resource Language="..." />
切换语言时，x:Static 绑定不会更新	x:Static 只会读取一次 — 请使用基于 INotifyPropertyChanged 的绑定方式
VS Code 中未重新生成 .Designer.cs	添加 <CoreCompileDependsOn>PrepareResources;$(CoreCompileDependsOn)</CoreCompileDependsOn>，然后运行 dotnet build

⚠️ NeutralLanguage 是必需项

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

平台声明 — 别忘了这些

iOS / Mac Catalyst

⚠️ 如果没有此项，iOS 不会在系统“设置”中提供你应用的语言选项：

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

Windows

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

Android

Android 会自动识别基于 .resx 的本地化。无需添加其他清单项。✅

运行时切换语言 — x:Static 陷阱

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


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

切换区域性时，请设置全部三个属性，否则格式设置会不一致：

// ✅ 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 布局 — 在页面级别设置 FlowDirection

<ContentPage FlowDirection="RightToLeft">
  <StackLayout FlowDirection="MatchParent" />
</ContentPage>


<ContentPage>
  <StackLayout FlowDirection="RightToLeft" />
</ContentPage>

VS Code 注意事项

⚠️ 保存时可能不会重新生成 .Designer.cs。请在 .csproj 中添加以下内容，并在修改 .resx 后运行 dotnet build：

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

选择方案

需求	方案
静态多语言字符串	使用带有 x:Static 绑定的 .resx 文件
运行时切换语言	使用 LocalizationResourceManager 和 INotifyPropertyChanged 绑定
特定区域性的图像	将图像命名为 banner_{culture}.png，或将路径存储在 .resx 中
RTL 支持	在页面级别设置 FlowDirection，使用 TextInfo.IsRightToLeft 检测
日期/数字格式	同时设置 CultureInfo.CurrentUICulture 和 CurrentCulture

快速检查清单

• 已在 .csproj 中设置 NeutralLanguage
• 默认的 AppResources.resx 包含所有键
• 每种目标语言都有自己的 AppResources.{culture}.resx
• iOS/Mac：CFBundleLocalizations 列出了所有受支持的语言
• Windows：Package.appxmanifest 声明了 <Resource Language="..." />
• RTL 区域性在页面/应用级别设置了 FlowDirection
• 运行时切换会设置全部三个属性：CurrentUICulture、CurrentCulture、AppResources.Culture
• 修改 .resx 后，dotnet build 会重新生成 .Designer.cs