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>
3.0 KiB
3.0 KiB
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'）