设计文档
本节包含 Annotate Translate 的设计规范、架构决策和数据结构设计文档。
UI 设计规范
遵循简洁、专业、不干扰的设计哲学。
核心原则:
- ✅ 简洁扁平设计（GitHub/VS Code 风格）
- ✅ 中性色调（灰色、蓝色系）
- ✅ 最小化动画（仅 200-300ms 过渡）
- ✅ 专业语调（无过度表情符号）
- ❌ 禁止弹跳、旋转、缩放、闪烁动画
- ❌ 禁止彩色渐变或霓虹色
- ❌ 禁止过度装饰元素
功能设计
单词本功能设计
详细的单词本功能技术设计文档，包括：
- 需求分析
- 数据结构设计
- 存储策略
- API 设计
- UI 设计草图
- 实现计划
数据结构设计
核心数据结构的设计和演进历史。
TranslationResult
翻译结果的完整数据结构，包括音标、释义、例句等。
Settings Schema
分层设置结构的设计，支持 Chrome Storage Sync 限制。
Vocabulary Data
词库数据格式，基于 ECDICT 的优化存储方案。
架构决策记录 (ADR)
记录重要的架构决策及其背后的考量。
ADR-001: 选择 Provider Pattern
背景: 需要支持多个翻译提供商，且能够运行时切换。
决策: 使用 Provider Pattern，定义统一的 TranslationProvider 接口。
优势:
- 易于扩展新提供商
- 运行时切换
- 独立配置和测试
劣势:
- 需要更多抽象层
- 接口需要覆盖所有提供商的功能
状态: ✅ 已采纳
ADR-002: 无构建流程
背景: 选择是否使用构建工具（Webpack、Vite 等）。
决策: 保持纯 Vanilla JavaScript，无构建流程。
优势:
- 开发体验简单
- 加载速度快
- 易于调试
- 降低学习门槛
劣势:
- 无法使用 TypeScript
- 无法使用 npm 包（除了 CDN）
- 手动管理依赖顺序
状态: ✅ 已采纳
ADR-003: Chrome Storage Sync 分层存储
背景: Chrome Storage Sync 有严格的大小限制（100KB 总量，8KB 单个 key）。
决策: 采用分层存储策略：
- Sync: 元数据和索引（轻量、同步）
- Local: 详细数据和缓存（大容量、本地）
优势:
- 绕过 Sync 大小限制
- 同步核心数据
- 本地存储大容量数据
劣势:
- 数据管理复杂
- 需要同步和一致性处理
状态: ✅ 已采纳（单词本功能）
ADR-004: 音标补充三层 Fallback
背景: 不同提供商返回的音标格式和可用性不一致。
决策: 实现三层音标补充机制：
- 提供商自带音标
- FreeDictionary API 补充（英文单词）
- 无音标
优势:
- 保证音标显示完整性
- 统一音标格式
- 提升用户体验
劣势:
- 增加 API 调用
- FreeDictionary 仅支持英文
状态: ✅ 已采纳
性能设计
缓存策略
- LRU 缓存 - 限制缓存大小，自动淘汰
- TTL - 30 分钟过期时间
- 缓存键 -
${text}:${sourceLang}:${targetLang}:${provider}
批量操作优化
- 并发控制 - 限制同时进行的翻译请求数
- 延迟 - 避免速率限制
- 中断机制 - AbortController 支持取消
内存优化
- 懒加载 - 词库数据按需加载
- 垃圾回收 - 定期清理过期缓存
- 分页 - 大列表分页显示
安全设计
HTML 清理
所有外部 HTML 内容（例句、释义）通过 HTMLSanitizer 清理，防止 XSS 攻击。
API Key 存储
API Key 存储在 Chrome Storage Sync 中，加密传输。
CSP 合规
遵循 Chrome Extension CSP 策略，无内联脚本。
国际化设计
消息格式
使用 Chrome i18n API，支持占位符和复数形式：
json
{
"message": {
"message": "翻译了 $COUNT$ 个单词",
"placeholders": {
"count": {
"content": "$1",
"example": "10"
}
}
}
}语言检测
自动检测浏览器语言，设置默认 UI 语言和目标语言。
可访问性设计
- 键盘导航 - 所有功能支持键盘操作
- ARIA 标签 - 为屏幕阅读器提供语义信息
- 对比度 - 符合 WCAG 2.1 AA 标准
- 焦点管理 - 清晰的焦点指示