edit | blame | history | raw

Round 2 研发任务拆解：语言检测与语言版本设置

状态：v0.1 研发拆解稿
所属子项目：02-P-NBL
Round：Round 2
日期：2026-06-03
输入文档：

1. 研发目标

Round 2 的研发目标是：

建立后端可验证的语言版本配置，并让前端 UI locale 跟随后端 effective language。

本轮不接入新模型，不改变模型选择，不做模型管理 UI。

2. 交付边界

2.1 必须交付

  • LanguageMode / LanguageID 配置字段。
  • 语言配置 normalize 与旧配置兼容。
  • en language profile。
  • 系统语言检测与 mockable detector。
  • ResolveEffectiveLanguage。
  • ConfigService 语言设置 API。
  • 前端 i18n 由后端 effective language 初始化。
  • 设置页语言版本控件。
  • 中文/English 文案补齐。
  • 自动化测试覆盖配置、语言解析、无效值 fallback。
  • QA 交接说明。

2.2 明确不交付

  • Moonshine profile。
  • Parakeet profile。
  • Qwen3-ASR profile。
  • 模型选择页。
  • 模型删除或回滚。
  • 30+ 语言列表。
  • 粤语独立语言。
  • 欧洲语言 UI。
  • 正式签名和 notarization。

3. 推荐任务顺序

T0 代码现状确认
T1 LanguageProfile 扩展
T2 Config 字段与 normalize
T3 系统语言检测
T4 EffectiveLanguage resolver
T5 ConfigService 语言 API
T6 前端 i18n 初始化改造
T7 设置页语言控件
T8 文案补齐
T9 自动化测试
T10 开发自查与 QA handoff

4. 任务明细

T0：代码现状确认

负责人：后端 + 前端
类型：准备任务

重点文件：

  • privatevoice.src/internal/model/registry.go
  • privatevoice.src/internal/model/profile.go
  • privatevoice.src/internal/config/config.go
  • privatevoice.src/services/config_service.go
  • privatevoice.src/frontend/src/lib/i18n/index.ts
  • privatevoice.src/frontend/src/lib/stores/config.ts
  • privatevoice.src/frontend/src/components/settings/GeneralPage.svelte
  • privatevoice.src/frontend/src/lib/i18n/zh.json
  • privatevoice.src/frontend/src/lib/i18n/en.json

完成标准：

  • 明确当前前端 locale 来源。
  • 明确当前后端配置保存路径。
  • 明确设置页控件样式和布局约束。

T1：LanguageProfile 扩展

负责人：后端
建议文件：

  • privatevoice.src/internal/model/profile.go
  • privatevoice.src/internal/model/registry.go

工作内容：

  • 确认 LanguageProfile 字段是否需要补 NativeName。
  • 新增 en profile。
  • 增加 DefaultLanguageID。
  • 增加 NormalizeLanguageID。
  • 增加 ListLanguageProfiles() 的稳定排序，避免前端选项顺序随机。

完成标准：

  • zh-CN 和 en 都可查询。
  • 未知语言 id 有明确 fallback。
  • 单元测试覆盖查询和列表顺序。

T2：Config 字段与 normalize

负责人：后端
建议文件：

  • privatevoice.src/internal/config/config.go

工作内容：

  • 新增字段：
  • LanguageMode string
  • LanguageID string
  • 新增常量：
  • LanguageModeAuto
  • LanguageModeManual
  • 新增 normalize：
  • NormalizeLanguageMode
  • NormalizeLanguageID
  • 老配置缺字段时默认：
  • LanguageMode=auto
  • LanguageID=zh-CN

完成标准：

  • 老 config.json 可正常加载。
  • 非法 LanguageMode 不导致启动失败。
  • 非法 LanguageID 不导致启动失败。
  • 保存配置不丢失原有字段。

T3：系统语言检测

负责人：后端
建议文件：

  • privatevoice.src/internal/language/detect.go
  • privatevoice.src/internal/language/detect_darwin.go
  • privatevoice.src/internal/language/detect_fallback.go

工作内容：

  • 实现 macOS 系统语言读取。
  • 提供环境变量 fallback。
  • 提供可 mock detector。
  • 把原始 locale normalize 为 zh-CN 或 en。

完成标准：

  • zh* 解析为 zh-CN。
  • en* 解析为 en。
  • 其他语言解析为 en。
  • 读取失败解析为 en。
  • 单元测试不依赖真实系统语言。

T4：EffectiveLanguage resolver

负责人：后端
建议文件：

  • privatevoice.src/internal/language/resolver.go

工作内容：

  • 实现 ResolveEffectiveLanguage(cfg, detectedLocale)。
  • manual 优先于 auto。
  • auto 依赖 detector。
  • 返回 EffectiveLanguageID、UILocale、DefaultModelID。

完成标准：

  • manual zh-CN 返回中文。
  • manual en 返回 English。
  • auto 中文系统返回中文。
  • auto English 系统返回 English。
  • auto 其他语言返回 English。

T5：ConfigService 语言 API

负责人：后端
建议文件：

  • privatevoice.src/services/config_service.go

工作内容：

  • 新增 LanguageSettings 返回结构。
  • 新增 GetLanguageSettings()。
  • 新增 SetLanguageAuto()。
  • 新增 SetLanguageManual(languageID string)。
  • API 返回 options：zh-CN、en。
  • 保存后返回新的 effective language。

完成标准：

  • 前端无需猜测系统语言。
  • 语言切换保存失败时返回错误。
  • 不改变 SelectedModelID。

T6：前端 i18n 初始化改造

负责人：前端
建议文件：

  • privatevoice.src/frontend/src/lib/i18n/index.ts
  • privatevoice.src/frontend/src/App.svelte
  • privatevoice.src/frontend/src/lib/stores/config.ts

工作内容：

  • 允许从后端设置 locale。
  • App 启动时调用 GetLanguageSettings()。
  • 根据 UILocale 调用 setLocale()。
  • 保留 navigator.language 作为后端调用失败时的兜底。
  • 增加 language store。

完成标准：

  • 中文 effective language 时 UI 中文。
  • English effective language 时 UI English。
  • 后端调用失败时 UI 仍可渲染。

T7：设置页语言控件

负责人：前端
建议文件：

  • privatevoice.src/frontend/src/components/settings/GeneralPage.svelte
  • privatevoice.src/frontend/src/lib/i18n/zh.json
  • privatevoice.src/frontend/src/lib/i18n/en.json

工作内容：

  • 在设置页新增“语言版本”区域。
  • 选项：
  • 自动
  • 中文
  • English
  • 切换后调用后端保存。
  • 保存成功后立即切换 UI locale。
  • 保持现有设置页视觉密度，不做营销式大卡片。

完成标准：

  • 选中状态清晰。
  • 切换时不影响其他设置。
  • 文案不溢出。
  • English UI 下设置页仍可读。

T8：文案补齐

负责人：前端
建议文件：

  • privatevoice.src/frontend/src/lib/i18n/zh.json
  • privatevoice.src/frontend/src/lib/i18n/en.json

工作内容：

  • 补充语言设置相关 key。
  • 检查 settings/onboarding 关键路径是否缺英文。
  • 避免把模型能力写成“English model”。

完成标准：

  • t() 不返回 key path。
  • 中文/English 文案含义一致。

T9：自动化测试

负责人：后端 + 前端

建议后端测试：

  • config language normalize。
  • language detector normalize。
  • EffectiveLanguage resolver。
  • LanguageRegistry 查询和排序。
  • ConfigService 保存语言设置。

建议前端测试或构建检查：

  • npm run build。
  • 如果项目已有前端测试，覆盖 language store 和 i18n 切换。

完成标准：

  • go test ./... 通过。
  • 前端构建通过。
  • 不新增明显 Svelte runtime warning。

T10：开发自查与 QA handoff

负责人：研发

交付内容：

  • 变更范围。
  • 自动化测试命令与结果。
  • 已知风险。
  • QA 数据准备说明。
  • 旧用户升级注意事项。

完成标准：

  • 可以进入 QA。
  • QA 能按 qa-test-plan.md 独立验证。

5. 实施注意事项

  • 不要在 Round 2 中把 English 默认模型改成 Moonshine。
  • 不要让语言切换触发模型下载。
  • 不要删除、移动、重命名用户现有模型目录。
  • 不要用前端 navigator.language 作为唯一事实源。
  • 不要把 LanguageID 和 SelectedModelID 混为一谈。
  • 不要在设置页做 30+ 语言列表。