偏好与本地化

AppPreferences

AppPreferences 是 @MainActor 上的 ObservableObject，包含三个可发布状态：

属性	默认值	UserDefaults 键
languageMode	system	app.languageMode
appearanceMode	system	app.appearanceMode
onboardingSeen	false	app.onboardingSeen

属性修改后立即写入 UserDefaults。不要在其他模块再维护同义键，否则恢复状态和测试会出现分叉。

语言解析顺序

用户显式选择 en / zh-Hans
  -> 对应语言 Bundle
  -> 当前语言缺少 key 时查英文 Bundle
  -> 英文仍缺少 key 时使用调用方 defaultValue

选择“跟随系统”时，L10n 在 en 与 zh-Hans 中匹配系统首选语言；没有匹配项时使用英文。当前支持的本地化资源位于：

• Resources/Shared/en.lproj/Localizable.strings
• Resources/Shared/zh-Hans.lproj/Localizable.strings

新增用户可见文本时，应同时增加两个语言文件中的键。需要插入变量时使用 L10n.formatted 和完整的本地化模板，不要拼接句子片段。

外观映射

AppAppearanceMode 将三种选择映射到 SwiftUI：

模式	ColorScheme?
跟随系统	nil
浅色	.light
深色	.dark

App 入口把结果传给 .preferredColorScheme。共享颜色应放在 AppTheme，并为 iOS 与 macOS 使用各自的系统背景色。

修改后的验证

偏好、本地化、持久化或设置页面有变化时至少运行：

task verify
task test

还需手动确认切换语言无需重启即可更新主要界面、缺失键回退英文、三种外观生效，以及首次运行状态可以重置。