6f5400ec4b
- 重构「灵感」模块为「发现」模块，统一页面命名与文案 - 新增flutter_tts语音朗读依赖与鸿蒙Nearby配对方式 - 添加Android/iOS/鸿蒙全平台桌面小组件支持（7种类型） - 完善文件传输模块，新增画布邀请消息与删除会话功能 - 优化协作画布光标广播节流逻辑，修复已知bug - 更新应用英文名与隐私政策入口，新增翻译API抽象层 - 移除用户中心多余的加号按钮，完善空状态组件类型
350 lines
11 KiB
Markdown
350 lines
11 KiB
Markdown
# 翻译助手 — 开发规格文档
|
||
|
||
> 创建时间: 2026-05-19
|
||
> 版本: v1.1
|
||
> 状态: 规划中
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
在「发现」页面新增「翻译助手」会话流页面，用户发送需要翻译的文本，系统自动回复翻译完成的内容。支持自动识别源语言、选择目标语言、多翻译API切换、会话管理等功能。
|
||
|
||
---
|
||
|
||
## 二、页面结构
|
||
|
||
### 2.1 入口位置
|
||
|
||
翻译助手作为**会话流列表**中的一个系统会话条目，与「稍后读」「天气诗词」「今日诗词」等并列显示。
|
||
|
||
- **主要入口**: 工作流页（InspirationPage）会话流列表 — 新增「🌐 翻译助手」会话行，**不置顶**，放在普通对话列表中，带 NEW 标签
|
||
- **未读红点**: 当用户发送翻译请求但翻译未完成（如网络中断、API超时、翻译中途返回）时，会话行显示小红点；用户点击进入翻译页面后清除红点
|
||
- **数据模型**: 使用 `ChatSession` 模型，`type: ChatSessionType.custom`，`id: 'translate'`，`isPinned: false`
|
||
- **路由**: `/translate` → `TranslatePage`
|
||
- **点击跳转**: 在 `_onSessionTap` 中增加 `case 'translate'` 路由跳转，跳转时清除 unreadCount
|
||
|
||
具体集成方式：
|
||
|
||
```dart
|
||
// chat_session_provider.dart → _buildSessions() 的 systemSessions 列表中新增：
|
||
ChatSession(
|
||
id: 'translate',
|
||
type: ChatSessionType.custom,
|
||
emoji: '🌐',
|
||
name: '翻译助手',
|
||
lastMessage: '多语言智能翻译 · 自动识别语言',
|
||
lastTime: now,
|
||
isPinned: false,
|
||
tag: 'NEW',
|
||
subtitle: '多语言智能翻译 · 自动识别语言',
|
||
route: '/translate',
|
||
),
|
||
|
||
// inspiration_page.dart → _onSessionTap() 中增加：
|
||
case 'translate':
|
||
ref.read(chatSessionProvider.notifier).markAsRead('translate');
|
||
context.appPush(AppRoutes.translate);
|
||
break;
|
||
```
|
||
|
||
### 2.1.1 未读红点逻辑
|
||
|
||
```
|
||
用户发送翻译请求
|
||
→ 翻译API调用中...
|
||
→ 如果翻译完成: unreadCount = 0 (无红点)
|
||
→ 如果翻译未完成(网络中断/API超时/中途退出):
|
||
→ unreadCount++ (显示红点)
|
||
→ 会话行 lastMessage 更新为 "翻译未完成"
|
||
|
||
用户点击进入翻译页面
|
||
→ 清除 unreadCount (红点消失)
|
||
→ 显示未完成的翻译消息，可重新翻译
|
||
```
|
||
|
||
### 2.2 翻译助手主页面布局
|
||
|
||
```
|
||
CupertinoPageScaffold
|
||
├── CupertinoNavigationBar
|
||
│ ├── ← 工作流 (previousPageTitle)
|
||
│ ├── 🌐 翻译助手 (middle)
|
||
│ └── 📋历史 | ⚙️设置 (trailing)
|
||
├── LanguagePairBar (源语言 → 目标语言)
|
||
│ ├── 🔍 自动检测 [AUTO]
|
||
│ ├── →
|
||
│ └── 🇨🇳 中文 (可点击切换)
|
||
├── LangChipBar (快捷语言选择，水平滚动)
|
||
│ ├── 🇨🇳中文 🇺🇸英语 🇯🇵日语 🇰🇷韩语 🇫🇷法语 🇩🇪德语 🇪🇸西语 🇷🇺俄语
|
||
│ └── 🌍更多
|
||
├── MessageArea (会话消息列表)
|
||
│ ├── EmptyState (空态：🌐 + 快捷翻译示例)
|
||
│ ├── UserBubble (用户发送的原文 + 语言标签)
|
||
│ └── AssistantBubble (翻译结果 + 语言标签 + 复制/朗读 + 检测信息)
|
||
├── InputBar (输入栏)
|
||
│ ├── TextField (输入需要翻译的文本)
|
||
│ └── SendButton (连同目标语言一起发送翻译请求)
|
||
└── TranslateSettingsSheet (底部弹出设置)
|
||
├── 翻译接口 (5个免费API可选)
|
||
├── 翻译设置 (自动检测/自动翻译/自动复制/发音朗读)
|
||
├── 会话管理 (会话列表 + 新建)
|
||
├── 数据管理 (导出/清空)
|
||
└── 调试 (接口测试)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、数据模型
|
||
|
||
### 3.1 TranslateMessage
|
||
|
||
```dart
|
||
class TranslateMessage {
|
||
final String id;
|
||
final String sessionId;
|
||
final TranslateMessageRole role; // user / assistant
|
||
final String content;
|
||
final String? sourceLang; // 源语言代码 (如 'en', 'zh')
|
||
final String? sourceLangName; // 源语言名称 (如 '英语', '中文')
|
||
final String? targetLang; // 目标语言代码
|
||
final String? targetLangName; // 目标语言名称
|
||
final bool autoDetected; // 是否自动检测
|
||
final String? apiProvider; // 使用的翻译API
|
||
final DateTime createdAt;
|
||
}
|
||
```
|
||
|
||
### 3.2 TranslateSession
|
||
|
||
```dart
|
||
class TranslateSession {
|
||
final String id;
|
||
final String name;
|
||
final String defaultTargetLang; // 默认目标语言
|
||
final String defaultApiProvider; // 默认API
|
||
final int messageCount;
|
||
final DateTime createdAt;
|
||
final DateTime updatedAt;
|
||
}
|
||
```
|
||
|
||
### 3.3 TranslateSettings
|
||
|
||
```dart
|
||
class TranslateSettings {
|
||
final String selectedApi; // 当前选中的API
|
||
final bool autoDetect; // 自动检测语言
|
||
final bool autoTranslate; // 自动翻译
|
||
final bool autoCopy; // 翻译后自动复制
|
||
final bool enableTts; // 发音朗读
|
||
final String defaultTargetLang; // 默认目标语言
|
||
}
|
||
```
|
||
|
||
### 3.4 SupportedLanguage
|
||
|
||
```dart
|
||
class SupportedLanguage {
|
||
final String code; // 'zh-CN', 'en', 'ja' ...
|
||
final String name; // '中文', '英语', '日语' ...
|
||
final String flag; // '🇨🇳', '🇺🇸', '🇯🇵' ...
|
||
final bool isPopular; // 是否常用语言（显示在快捷选择栏）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、翻译API接口
|
||
|
||
### 4.1 API列表
|
||
|
||
| # | 名称 | 端点 | 特点 | 语言检测 |
|
||
|---|------|------|------|----------|
|
||
| 1 | Google Translate | `translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl={target}&dt=t&q={text}` | 免费·100+语言 | ✅ sl=auto |
|
||
| 2 | Bing Translator | 通过Bing Token API获取翻译 | 免费·70+语言 | ✅ |
|
||
| 3 | LibreTranslate | `libretranslate.de/translate` POST | 开源免费·30+语言 | ✅ |
|
||
| 4 | MyMemory API | `api.mymemory.translated.net/get?q={text}&langpair={src}|{tgt}` | 免费·无需Key | ❌ 需指定 |
|
||
| 5 | AppWorlds 翻译 | `translate.appworlds.cn` | 免费·国内直连·100+语言 | ✅ |
|
||
|
||
### 4.2 API抽象层
|
||
|
||
```dart
|
||
abstract class TranslateApiService {
|
||
Future<TranslateResult> translate({
|
||
required String text,
|
||
required String targetLang,
|
||
String? sourceLang, // null = 自动检测
|
||
});
|
||
|
||
Future<LanguageDetectResult> detectLanguage(String text);
|
||
|
||
String get name;
|
||
String get description;
|
||
bool get supportsAutoDetect;
|
||
}
|
||
```
|
||
|
||
### 4.3 降级策略
|
||
|
||
1. 优先使用用户选择的API
|
||
2. 如果失败，自动切换到下一个可用API
|
||
3. 所有API都失败时，显示错误提示
|
||
|
||
---
|
||
|
||
## 五、文件结构规划
|
||
|
||
```
|
||
lib/features/inspiration/
|
||
├── models/
|
||
│ ├── translate_message.dart // 翻译消息模型
|
||
│ ├── translate_session.dart // 翻译会话模型
|
||
│ └── translate_language.dart // 支持语言模型
|
||
├── providers/
|
||
│ ├── translate_provider.dart // 翻译核心状态
|
||
│ └── translate_settings_provider.dart // 翻译设置状态
|
||
├── services/
|
||
│ ├── translate_api_service.dart // API抽象层
|
||
│ ├── google_translate_service.dart
|
||
│ ├── bing_translate_service.dart
|
||
│ ├── libre_translate_service.dart
|
||
│ ├── mymemory_translate_service.dart
|
||
│ └── appworlds_translate_service.dart
|
||
├── presentation/
|
||
│ └── pages/
|
||
│ ├── translate_page.dart // 翻译助手主页面
|
||
│ └── translate_settings_page.dart // 翻译设置页面
|
||
```
|
||
|
||
---
|
||
|
||
## 六、交互流程
|
||
|
||
### 6.1 翻译流程
|
||
|
||
```
|
||
用户输入文本 → 选择目标语言(Chip/语言对) → 点击发送
|
||
→ 显示用户消息气泡(原文+语言标签)
|
||
→ 显示typing动画
|
||
→ 调用翻译API(自动检测源语言)
|
||
→ 显示翻译结果气泡(译文+语言标签+复制/朗读+检测信息)
|
||
```
|
||
|
||
### 6.2 设置流程
|
||
|
||
```
|
||
点击右上角⚙️ → 底部弹出设置面板
|
||
→ 切换翻译API
|
||
→ 开关自动检测/自动翻译/自动复制/朗读
|
||
→ 管理翻译会话
|
||
→ 导出/清空数据
|
||
→ 接口测试(调试)
|
||
```
|
||
|
||
### 6.3 语言选择流程
|
||
|
||
```
|
||
点击语言对中的目标语言 → 弹出语言选择面板
|
||
→ 常用语言(Chip快捷选择)
|
||
→ 全部语言(搜索+列表)
|
||
→ 选择后更新语言对显示
|
||
```
|
||
|
||
---
|
||
|
||
## 七、设计规范
|
||
|
||
### 7.1 组件复用
|
||
|
||
- 消息气泡: 复用现有 `ChatBubble` 组件，扩展翻译元数据
|
||
- 输入栏: 参考 `ChatFlowInputBar`，简化为纯文本输入
|
||
- 设置面板: 参考 `ChatSettingsPage` 的分组样式
|
||
- 语言Chip: 参考现有分类标签 `_TagChip` 样式
|
||
|
||
### 7.2 主题适配
|
||
|
||
- 使用 `AppTheme.ext(context)` 获取设计令牌
|
||
- 支持日间/夜间/AMOLED三种主题
|
||
- 毛玻璃效果使用 `GlassContainer`
|
||
|
||
### 7.3 动画
|
||
|
||
- 消息入场: `flutter_animate` fadeIn + slideY
|
||
- Typing指示器: 三点跳动动画
|
||
- 语言Chip选中: 缩放+颜色过渡
|
||
|
||
---
|
||
|
||
## 八、开发任务清单
|
||
|
||
### Phase 1: 基础框架
|
||
- [ ] 创建翻译数据模型 (TranslateMessage, TranslateSession, TranslateLanguage)
|
||
- [ ] 创建API抽象层 (TranslateApiService)
|
||
- [ ] 实现 Google Translate API 服务
|
||
- [ ] 创建翻译状态管理 (TranslateProvider)
|
||
- [ ] 创建翻译设置状态 (TranslateSettingsProvider)
|
||
|
||
### Phase 2: 页面开发
|
||
- [ ] 创建翻译助手主页面 (TranslatePage)
|
||
- [ ] NavigationBar (返回+标题+设置按钮)
|
||
- [ ] LanguagePairBar (源语言→目标语言)
|
||
- [ ] LangChipBar (快捷语言选择)
|
||
- [ ] MessageArea (消息列表+空态)
|
||
- [ ] InputBar (输入+发送)
|
||
- [ ] 创建翻译设置页面 (TranslateSettingsSheet)
|
||
- [ ] API选择列表
|
||
- [ ] 翻译设置开关
|
||
- [ ] 会话管理
|
||
- [ ] 数据管理
|
||
|
||
### Phase 3: API实现
|
||
- [ ] 实现 Bing Translator API 服务
|
||
- [ ] 实现 LibreTranslate API 服务
|
||
- [ ] 实现 MyMemory API 服务
|
||
- [ ] 实现 AppWorlds 翻译 API 服务
|
||
- [ ] API降级策略实现
|
||
|
||
### Phase 4: 集成
|
||
- [ ] 在 chat_session_provider.dart 的 systemSessions 列表中添加翻译助手会话条目
|
||
- [ ] 在 inspiration_page.dart 的 _onSessionTap() 中增加 translate 路由跳转
|
||
- [ ] 路由注册 `/translate` → TranslatePage
|
||
- [ ] 数据持久化 (Drift数据库)
|
||
- [ ] 会话管理 (新建/切换/删除)
|
||
|
||
### Phase 5: 增强
|
||
- [ ] 自动语言检测
|
||
- [ ] 翻译后自动复制
|
||
- [ ] TTS发音朗读
|
||
- [ ] 接口测试调试工具
|
||
- [ ] 导出/导入翻译记录
|
||
|
||
---
|
||
|
||
## 九、API测试脚本
|
||
|
||
需编写测试脚本验证5个翻译API的可用性：
|
||
|
||
```bash
|
||
# 测试命令
|
||
dart run test_translate_api.dart
|
||
```
|
||
|
||
测试内容：
|
||
1. 基本翻译功能 (中→英, 英→中, 日→中)
|
||
2. 自动语言检测
|
||
3. 响应时间
|
||
4. 错误处理
|
||
5. 并发请求限制
|
||
|
||
---
|
||
|
||
## 十、注意事项
|
||
|
||
1. 所有API调用需在 `TranslateApiService` 抽象层统一处理，便于切换和降级
|
||
2. 翻译消息需持久化到本地数据库，支持离线查看历史
|
||
3. 语言代码需统一为 ISO 639-1 标准
|
||
4. 输入文本长度需限制（建议5000字符），避免API超时
|
||
5. 需处理网络异常、API限流、空翻译等边界情况
|
||
6. 设置项需持久化到 KV Storage
|