xianyan/docs/spec/translate_assistant_spec.md

翻译助手 — 开发规格文档

创建时间: 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

具体集成方式：

// 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

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

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

class TranslateSettings {
  final String selectedApi;       // 当前选中的API
  final bool autoDetect;          // 自动检测语言
  final bool autoTranslate;       // 自动翻译
  final bool autoCopy;            // 翻译后自动复制
  final bool enableTts;           // 发音朗读
  final String defaultTargetLang; // 默认目标语言
}

3.4 SupportedLanguage

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抽象层

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的可用性：

# 测试命令
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