Initial Commit

2025-12-23 01:38:53 +08:00
commit d0417339c1
@@ -0,0 +1,30 @@
+# 设计：多语言支持
+
+## 架构
+
+应用使用 `react-i18next` 进行国际化，并配合 `i18next-browser-languagedetector` 进行语言检测。配置集中在 `src/localization/i18n.ts` 中。
+
+### 语言资源
+
+翻译资源将作为 JSON 对象构建在 `i18n.ts` 中（如果太大则分文件）。
+我们将在 `resources` 对象中添加 `zh-CN` 键。
+
+### 默认语言策略
+
+我们将引入 `LanguageDetector` 插件。
+`i18n.use(LanguageDetector).init({...})` 将被配置为首先检查 `localStorage`，然后检查 `navigator`（浏览器/系统语言）。
+`fallbackLng` 将保持为 `'en'`，作为最后的兜底。
+
+### 键映射
+
+我们将把现有的英文字符串映射到语义键（例如 `home.title`, `settings.theme`）。
+
+## 数据流
+
+1. 应用启动。
+2. `i18next` 初始化，通过 `LanguageDetector` 确定语言：
+   * 检查 `localStorage` 是否有保存的偏好。
+   * 如果无，检查 `navigator.language`。
+   * 如果检测到的语言受支持（`en` 或 `zh-CN`），则使用该语言。
+   * 否则，使用 `fallbackLng` (`en`)。
+3. 组件使用 `useTranslation` hook 根据当前语言获取字符串。
@@ -0,0 +1,41 @@
+# 提案：应用本地化（自动检测系统语言）
+
+**变更 ID：** `localize-app-auto-detect`
+
+## 摘要
+
+为 Antigravity Manager 应用添加多语言支持，并根据用户的操作系统语言自动设置默认语言。如果系统语言不受支持，则回退到英语。这包括更新 i18n 配置，添加中文翻译资源，并集成语言检测插件。
+
+## 动机
+
+为了提供最佳的用户体验，应用应该能够适应用户的首选语言环境。自动检测系统语言可以减少用户的配置步骤，提供更自然的初次使用体验。
+
+## 建议变更
+
+1. **集成语言检测：** 安装并配置 `i18next-browser-languagedetector` 以自动检测用户语言。
+2. **更新 i18n 配置：** 修改 `src/localization/i18n.ts`，启用语言检测，并设置适当的回退语言（英语）。
+3. **添加中文资源：** 为 `zh-CN` 创建一个新的翻译资源文件，包含所有应用字符串。
+4. **更新语言操作：** 确保 `src/actions/language.ts` 正确处理自动检测和手动覆盖的逻辑。
+5. **UI 更新：** 确保所有 UI 组件使用翻译键而不是硬编码字符串。
+
+## 考虑的替代方案
+
+* **强制默认中文：** 已拒绝，为了适应更广泛的国际用户群体，并尊重用户的系统设置。
+* **强制默认英语：** 已拒绝，同上。
+
+## 风险
+
+* **检测失败：** 在某些特殊环境（如 Linux 某些发行版）下，语言检测可能不准确，需要确保回退机制可靠。
+
+## 验收标准
+
+1. **自动检测：**
+   * 在系统语言设置为中文（简体）的环境下启动应用，应用界面默认显示为中文。
+   * 在系统语言设置为英语或其他非中文语言的环境下启动应用，应用界面默认显示为英语。
+2. **手动切换：**
+   * 用户可以在设置页面将语言从中文切换到英语，界面应立即更新，无需重启。
+   * 用户可以在设置页面将语言从英语切换到中文，界面应立即更新，无需重启。
+3. **持久化：**
+   * 用户手动更改语言后，重启应用，应用应保持用户选择的语言，而不是重新检测系统语言。
+4. **完整性：**
+   * 应用的所有可见文本（包括主页、设置页、状态栏、弹窗提示）都应正确显示对应的语言，没有遗漏的硬编码字符串。
@@ -0,0 +1,59 @@
+# 规格：本地化
+
+## ADDED Requirements
+
+### Requirement: 自动语言检测
+
+应用在首次启动时 MUST 自动检测用户的系统语言并设置相应的界面语言。
+
+#### Scenario: 系统语言为中文
+
+Given 用户首次打开应用
+And 用户的系统语言设置为中文 (zh-CN)
+And 本地存储中没有保存语言偏好
+When 应用加载时
+Then 界面应该显示为简体中文 (`zh-CN`)
+
+#### Scenario: 系统语言为其他（非中文）
+
+Given 用户首次打开应用
+And 用户的系统语言设置为法语 (fr)
+And 本地存储中没有保存语言偏好
+When 应用加载时
+Then 界面应该回退显示为英语 (`en`)
+
+### Requirement: 语言切换
+
+用户 MUST 能够在支持的语言之间切换，且手动选择 MUST 覆盖自动检测。
+
+#### Scenario: 切换语言
+
+Given 用户在设置页面
+When 用户从语言下拉菜单中选择 "English"
+Then 界面应该立即切换为英语
+And 偏好应该保存到本地存储
+
+### Requirement: 持久化
+
+用户的手动语言偏好 MUST 在会话之间持久化，并优先于系统语言。
+
+#### Scenario: 持久化语言偏好
+
+Given 用户已手动选择 "English" 作为首选语言
+And 用户的系统语言设置为中文
+When 用户重启应用
+Then 界面应该显示为英语（尊重用户选择）
+
+## MODIFIED Requirements
+
+### Requirement: i18n 配置更新
+
+i18n 配置 MUST 更新以支持语言检测插件。
+
+#### Scenario: i18n 配置
+
+`src/localization/i18n.ts` 文件必须更新为：
+
+1. 集成 `i18next-browser-languagedetector`。
+2. 配置检测顺序：`['localStorage', 'navigator']`。
+3. 包含 `zh-CN` 资源对象。
@@ -0,0 +1,10 @@
+# 任务：应用本地化（自动检测系统语言）
+
+* \[x] 安装 `i18next-browser-languagedetector` 依赖。 <!-- id: install-dependency -->
+* \[x] 更新 `src/localization/i18n.ts` 以配置语言检测器并包含 `zh-CN` 资源。 <!-- id: update-i18n-config -->
+* \[x] 验证 `src/actions/language.ts` 逻辑，确保与自动检测兼容。 <!-- id: verify-language-actions -->
+* \[x] 更新 `src/components/StatusBar.tsx` 以使用翻译。 <!-- id: localize-statusbar -->
+* \[x] 更新 `src/components/AccountCard.tsx` 以使用翻译。 <!-- id: localize-accountcard -->
+* \[x] 更新 `src/pages/index.tsx`（主页）以使用翻译。 <!-- id: localize-homepage -->
+* \[x] 更新 `src/pages/settings.tsx` 以使用翻译并添加语言切换器。 <!-- id: localize-settings -->
+* \[x] 运行应用验证语言检测和手动切换功能。 <!-- id: verify-localization -->