feat(i18n): 完成全量 UI 文本国际化,替换所有硬编码中文为 AppLocalizations 调用

- core/localization: 新增约 60 个翻译键(含参数化方法),中英双语覆盖
- shared/widgets: CommonDialog 默认参数国际化
- features/home: 完成页操作步骤指引、状态栏串口连接状态、程序列表状态标签
- features/programs: 表头状态列、表单验证提示、导入/模板操作反馈、删除确认(参数化)
- features/program_detail: 步骤列表/表单标题、删除确认、速度档位显示(参数化)
- features/device: run_state_provider 错误消息改为错误码
- features/settings: 升级页、密码面板、语言面板、U盘导入面板、串口配置面板全部替换

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Developer
2026-06-12 15:09:47 +08:00
parent 5d65744618
commit 3d849bd468
23 changed files with 688 additions and 127 deletions

View File

@@ -0,0 +1,49 @@
## ADDED Requirements
### Requirement: 完整的 UI 文本国际化覆盖
应用 SHALL 通过 `AppLocalizations` 提供所有面向用户的 UI 文本,禁止在 widget 构建逻辑中使用字面量中文字符串。
#### Scenario: 所有可见文本通过翻译函数获取
- **WHEN** 开发者在任何 widget 的 `build()` 方法、`AppBar` 标题、`SnackBar` 内容、`Dialog` 文本或按钮文案中显示文本
- **THEN** 文本必须来自 `AppLocalizations.of(context)` 的 getter 或方法调用,不得直接写中文字面量
#### Scenario: 静态分析检测硬编码中文
- **WHEN** 运行 `flutter analyze` 或代码评审检查 `lib/` 目录下任意 `.dart` 文件中 widget 渲染部分
- **THEN** 不应出现包含中文字符(`[一-鿿]`)的字面量字符串
### Requirement: 中英双语翻译完整性
`AppLocalizations` SHALL 为所有翻译键同时提供中文(`zh`)和英文(`en`)两种语言的取值,避免运行时回退到键名或硬编码默认值。
#### Scenario: 翻译键同时存在于两种语言
- **WHEN** 新增任意翻译键到 `_localizedValues['zh']`
- **THEN** `_localizedValues['en']` 必须包含同名键,且值为对应的英文翻译
#### Scenario: 切换语言后所有界面文本即时更新
- **WHEN** 用户在系统设置中将语言从中文切换到英文
- **THEN** 应用所有页面(首页、程序管理、程序详情、运行控制、系统设置、完成页)的 UI 文本应立即变为英文,无需重启应用
### Requirement: 非 BuildContext 场景的本地化支持
`AppLocalizations` SHALL 提供在没有 `BuildContext` 的场景(如 Provider/Service 层抛出错误消息、日志)中获取当前语言文本的方式,或明确将这些场景排除在国际化范围之外。
#### Scenario: Service 层错误消息的本地化
- **WHEN** 设备运行 Service 需要向 UI 反馈错误(如串口连接失败)
- **THEN** Service 层应返回稳定的错误码或英文键名,由 UI 层通过 `AppLocalizations` 转换为本地化文本展示给用户
#### Scenario: 调试日志保留原始语言
- **WHEN** 代码通过 `dart:developer``log()` 或类似 API 输出调试日志
- **THEN** 允许保留中文日志内容,无需国际化(仅面向开发者)
### Requirement: 单复数与参数化文本
`AppLocalizations` SHALL 支持包含动态参数(如数量、程序名称)的翻译,禁止通过字符串拼接构造可见文本。
#### Scenario: 带参数的翻译方法
- **WHEN** 显示形如「成功导入 5 个程序」的消息
- **THEN** `AppLocalizations` 应提供方法形式(如 `programsImportedCount(int n)`)返回完整本地化字符串,而不是要求调用方拼接 `importSuccess + n + programsImported`
#### Scenario: 替换现有拼接式调用
- **WHEN** 重构现有代码中通过 `'${l.importSuccess} $count ${l.programsImported}'` 形式拼接的字符串
- **THEN** 应替换为单个参数化方法调用,确保英文语序自然(如 `'Successfully imported $count programs'`