docs: translate repository documentation to English (#72)
This commit is contained in:
8 files changed
+456
-441
No files matched your search
@@ -1,30 +1,30 @@
|
||||
# 设计：多语言支持
|
||||
# Design: Multilingual Support
|
||||
|
||||
## 架构
|
||||
## Architecture
|
||||
|
||||
应用使用 `react-i18next` 进行国际化，并配合 `i18next-browser-languagedetector` 进行语言检测。配置集中在 `src/localization/i18n.ts` 中。
|
||||
The application uses `react-i18next` for i18n and `i18next-browser-languagedetector` for language detection. Configuration is centralized in `src/localization/i18n.ts`.
|
||||
|
||||
### 语言资源
|
||||
### Language Resources
|
||||
|
||||
翻译资源将作为 JSON 对象构建在 `i18n.ts` 中（如果太大则分文件）。
|
||||
我们将在 `resources` 对象中添加 `zh-CN` 键。
|
||||
Translation resources are built as JSON objects in `i18n.ts` (or split into files if they grow large).
|
||||
We add a `zh-CN` key in the `resources` object.
|
||||
|
||||
### 默认语言策略
|
||||
### Default Language Strategy
|
||||
|
||||
我们将引入 `LanguageDetector` 插件。
|
||||
`i18n.use(LanguageDetector).init({...})` 将被配置为首先检查 `localStorage`，然后检查 `navigator`（浏览器/系统语言）。
|
||||
`fallbackLng` 将保持为 `'en'`，作为最后的兜底。
|
||||
We introduce the `LanguageDetector` plugin.
|
||||
`i18n.use(LanguageDetector).init({...})` is configured to check `localStorage` first, then `navigator` (browser/system language).
|
||||
`fallbackLng` remains `'en'` as the final fallback.
|
||||
|
||||
### 键映射
|
||||
### Key Mapping
|
||||
|
||||
我们将把现有的英文字符串映射到语义键（例如 `home.title`, `settings.theme`）。
|
||||
Existing English strings are mapped to semantic keys (for example, `home.title`, `settings.theme`).
|
||||
|
||||
## 数据流
|
||||
## Data Flow
|
||||
|
||||
1. 应用启动。
|
||||
2. `i18next` 初始化，通过 `LanguageDetector` 确定语言：
|
||||
* 检查 `localStorage` 是否有保存的偏好。
|
||||
* 如果无，检查 `navigator.language`。
|
||||
* 如果检测到的语言受支持（`en` 或 `zh-CN`），则使用该语言。
|
||||
* 否则，使用 `fallbackLng` (`en`)。
|
||||
3. 组件使用 `useTranslation` hook 根据当前语言获取字符串。
|
||||
1. App starts.
|
||||
2. `i18next` initializes and determines language via `LanguageDetector`:
|
||||
* Check whether `localStorage` has a saved preference.
|
||||
* If not, check `navigator.language`.
|
||||
* If detected language is supported (`en` or `zh-CN`), use it.
|
||||
* Otherwise, use `fallbackLng` (`en`).
|
||||
3. Components use `useTranslation` to resolve strings for the active language.
|
||||
@@ -1,41 +1,41 @@
|
||||
# 提案：应用本地化（自动检测系统语言）
|
||||
# Proposal: App Localization (Automatic System Language Detection)
|
||||
|
||||
**变更 ID：** `localize-app-auto-detect`
|
||||
**Change ID:** `localize-app-auto-detect`
|
||||
|
||||
## 摘要
|
||||
## Summary
|
||||
|
||||
为 Antigravity Manager 应用添加多语言支持，并根据用户的操作系统语言自动设置默认语言。如果系统语言不受支持，则回退到英语。这包括更新 i18n 配置，添加中文翻译资源，并集成语言检测插件。
|
||||
Add multilingual support to Antigravity Manager and automatically set the default UI language based on the user's OS language. If the OS language is unsupported, fall back to English. This includes updating i18n configuration, adding Chinese translation resources, and integrating a language detection plugin.
|
||||
|
||||
## 动机
|
||||
## Motivation
|
||||
|
||||
为了提供最佳的用户体验，应用应该能够适应用户的首选语言环境。自动检测系统语言可以减少用户的配置步骤，提供更自然的初次使用体验。
|
||||
To provide a better user experience, the app should adapt to users' preferred language environment. Automatically detecting system language reduces setup effort and improves first-run experience.
|
||||
|
||||
## 建议变更
|
||||
## Proposed Changes
|
||||
|
||||
1. **集成语言检测：** 安装并配置 `i18next-browser-languagedetector` 以自动检测用户语言。
|
||||
2. **更新 i18n 配置：** 修改 `src/localization/i18n.ts`，启用语言检测，并设置适当的回退语言（英语）。
|
||||
3. **添加中文资源：** 为 `zh-CN` 创建一个新的翻译资源文件，包含所有应用字符串。
|
||||
4. **更新语言操作：** 确保 `src/actions/language.ts` 正确处理自动检测和手动覆盖的逻辑。
|
||||
5. **UI 更新：** 确保所有 UI 组件使用翻译键而不是硬编码字符串。
|
||||
1. **Integrate language detection:** Install and configure `i18next-browser-languagedetector` to auto-detect user language.
|
||||
2. **Update i18n config:** Modify `src/localization/i18n.ts` to enable language detection and define a fallback language (English).
|
||||
3. **Add Chinese resources:** Create `zh-CN` translation resources covering all app strings.
|
||||
4. **Update language actions:** Ensure `src/actions/language.ts` correctly handles auto-detection and manual override.
|
||||
5. **UI updates:** Ensure all UI components use translation keys instead of hardcoded text.
|
||||
|
||||
## 考虑的替代方案
|
||||
## Alternatives Considered
|
||||
|
||||
* **强制默认中文：** 已拒绝，为了适应更广泛的国际用户群体，并尊重用户的系统设置。
|
||||
* **强制默认英语：** 已拒绝，同上。
|
||||
* **Force default Chinese:** Rejected, to support a broader international user base and respect system settings.
|
||||
* **Force default English:** Rejected, same reason.
|
||||
|
||||
## 风险
|
||||
## Risks
|
||||
|
||||
* **检测失败：** 在某些特殊环境（如 Linux 某些发行版）下，语言检测可能不准确，需要确保回退机制可靠。
|
||||
* **Detection failure:** In certain environments (for example, some Linux distros), language detection may be inaccurate. Fallback behavior must remain reliable.
|
||||
|
||||
## 验收标准
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **自动检测：**
|
||||
* 在系统语言设置为中文（简体）的环境下启动应用，应用界面默认显示为中文。
|
||||
* 在系统语言设置为英语或其他非中文语言的环境下启动应用，应用界面默认显示为英语。
|
||||
2. **手动切换：**
|
||||
* 用户可以在设置页面将语言从中文切换到英语，界面应立即更新，无需重启。
|
||||
* 用户可以在设置页面将语言从英语切换到中文，界面应立即更新，无需重启。
|
||||
3. **持久化：**
|
||||
* 用户手动更改语言后，重启应用，应用应保持用户选择的语言，而不是重新检测系统语言。
|
||||
4. **完整性：**
|
||||
* 应用的所有可见文本（包括主页、设置页、状态栏、弹窗提示）都应正确显示对应的语言，没有遗漏的硬编码字符串。
|
||||
1. **Automatic detection:**
|
||||
* When OS language is Simplified Chinese, app defaults to Chinese on first launch.
|
||||
* When OS language is English or another non-Chinese language, app defaults to English on first launch.
|
||||
2. **Manual switching:**
|
||||
* Users can switch from Chinese to English in Settings, and UI updates immediately without restart.
|
||||
* Users can switch from English to Chinese in Settings, and UI updates immediately without restart.
|
||||
3. **Persistence:**
|
||||
* After users manually change language, app restart preserves the selected language instead of re-detecting.
|
||||
4. **Completeness:**
|
||||
* All visible strings (home page, settings page, status bar, popups) render correctly in the selected language with no leftover hardcoded text.
|
||||
@@ -1,59 +1,59 @@
|
||||
# 规格：本地化
|
||||
# Spec: Localization
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 自动语言检测
|
||||
### Requirement: Automatic Language Detection
|
||||
|
||||
应用在首次启动时 MUST 自动检测用户的系统语言并设置相应的界面语言。
|
||||
On first launch, the application MUST automatically detect the user's system language and set the corresponding UI language.
|
||||
|
||||
#### Scenario: 系统语言为中文
|
||||
#### Scenario: System language is Chinese
|
||||
|
||||
Given 用户首次打开应用
|
||||
And 用户的系统语言设置为中文 (zh-CN)
|
||||
And 本地存储中没有保存语言偏好
|
||||
When 应用加载时
|
||||
Then 界面应该显示为简体中文 (`zh-CN`)
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to Chinese (`zh-CN`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should be displayed in Simplified Chinese (`zh-CN`)
|
||||
|
||||
#### Scenario: 系统语言为其他（非中文）
|
||||
#### Scenario: System language is non-Chinese
|
||||
|
||||
Given 用户首次打开应用
|
||||
And 用户的系统语言设置为法语 (fr)
|
||||
And 本地存储中没有保存语言偏好
|
||||
When 应用加载时
|
||||
Then 界面应该回退显示为英语 (`en`)
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to French (`fr`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should fall back to English (`en`)
|
||||
|
||||
### Requirement: 语言切换
|
||||
### Requirement: Language Switching
|
||||
|
||||
用户 MUST 能够在支持的语言之间切换，且手动选择 MUST 覆盖自动检测。
|
||||
Users MUST be able to switch between supported languages, and manual selection MUST override automatic detection.
|
||||
|
||||
#### Scenario: 切换语言
|
||||
#### Scenario: Switch language
|
||||
|
||||
Given 用户在设置页面
|
||||
When 用户从语言下拉菜单中选择 "English"
|
||||
Then 界面应该立即切换为英语
|
||||
And 偏好应该保存到本地存储
|
||||
Given the user is on the settings page
|
||||
When the user selects "English" from the language dropdown
|
||||
Then the UI should switch to English immediately
|
||||
And the preference should be saved to local storage
|
||||
|
||||
### Requirement: 持久化
|
||||
### Requirement: Persistence
|
||||
|
||||
用户的手动语言偏好 MUST 在会话之间持久化，并优先于系统语言。
|
||||
The user's manual language preference MUST persist across sessions and take precedence over system language.
|
||||
|
||||
#### Scenario: 持久化语言偏好
|
||||
#### Scenario: Persist language preference
|
||||
|
||||
Given 用户已手动选择 "English" 作为首选语言
|
||||
And 用户的系统语言设置为中文
|
||||
When 用户重启应用
|
||||
Then 界面应该显示为英语（尊重用户选择）
|
||||
Given the user has manually selected "English" as preferred language
|
||||
And the user's system language is Chinese
|
||||
When the user restarts the app
|
||||
Then the UI should display English (respecting user preference)
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: i18n 配置更新
|
||||
### Requirement: Update i18n Configuration
|
||||
|
||||
i18n 配置 MUST 更新以支持语言检测插件。
|
||||
i18n configuration MUST be updated to support the language detection plugin.
|
||||
|
||||
#### Scenario: i18n 配置
|
||||
#### Scenario: i18n configuration
|
||||
|
||||
`src/localization/i18n.ts` 文件必须更新为：
|
||||
`src/localization/i18n.ts` must be updated to:
|
||||
|
||||
1. 集成 `i18next-browser-languagedetector`。
|
||||
2. 配置检测顺序：`['localStorage', 'navigator']`。
|
||||
3. 包含 `zh-CN` 资源对象。
|
||||
1. Integrate `i18next-browser-languagedetector`.
|
||||
2. Configure detection order as `['localStorage', 'navigator']`.
|
||||
3. Include `zh-CN` resource objects.
|
||||
@@ -1,10 +1,10 @@
|
||||
# 任务：应用本地化（自动检测系统语言）
|
||||
# Tasks: App Localization (Automatic System Language Detection)
|
||||
|
||||
* \[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 -->
|
||||
* \[x] Install `i18next-browser-languagedetector`. <!-- id: install-dependency -->
|
||||
* \[x] Update `src/localization/i18n.ts` to configure language detection and include `zh-CN` resources. <!-- id: update-i18n-config -->
|
||||
* \[x] Verify `src/actions/language.ts` logic is compatible with auto-detection. <!-- id: verify-language-actions -->
|
||||
* \[x] Update `src/components/StatusBar.tsx` to use translations. <!-- id: localize-statusbar -->
|
||||
* \[x] Update `src/components/AccountCard.tsx` to use translations. <!-- id: localize-accountcard -->
|
||||
* \[x] Update `src/pages/index.tsx` (home page) to use translations. <!-- id: localize-homepage -->
|
||||
* \[x] Update `src/pages/settings.tsx` to use translations and add a language switcher. <!-- id: localize-settings -->
|
||||
* \[x] Run the app to verify language detection and manual switching. <!-- id: verify-localization -->
|
||||
Reference in new issue
Block a user