3d849bd468
- 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>
50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
Markdown
## 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'`）
|