DocTranslate
一款 VSCode 悬浮文档翻译插件，支持 AI 翻译悬停文本，可自定义翻译 API 和提示词。
🌟 特性
- ✨ 悬浮翻译：在代码中悬停鼠标即可自动翻译文本内容
- 🔄 原文/译文切换：轻松切换显示原文或译文
- 💾 智能缓存：自动缓存翻译结果，避免重复请求，支持30天过期清理
- 🔧 高度自定义：支持自定义API接口（阿里百炼、本地大模型等）、模型名称和提示词模板
- 📋 缓存管理：提供可视化缓存管理界面，可查看、编辑、删除缓存内容
- 🛠️ 手动/自动模式：支持自动翻译和手动翻译两种模式，灵活适应不同需求
- 🌐 多API支持：兼容OpenAI格式的API接口，默认使用阿里百炼
- 📝 上下文感知：可选择包含光标附近的代码上下文，提高翻译准确性
📦 安装
市场安装
- 打开 VSCode 扩展市场
- 搜索 "DocTranslate"
- 点击安装
命令行安装
ext install doctranslate.doctranslate
⚙️ 配置
在 VSCode 设置中搜索 hoverTranslator，配置以下选项：
| 配置项 |
类型 |
默认值 |
说明 |
baseURL |
string |
https://dashscope.aliyuncs.com/compatible-mode/v1 |
API 接口地址，支持阿里百炼等OpenAI格式接口 |
apiKey |
string |
"" |
API 密钥 |
model |
string |
qwen3-next-80b-a3b-instruct |
使用的AI模型名称 |
promptTemplate |
string |
简短解释一下，不要回复其他内容：${content} |
提示词模板，${content} 为原文占位符 |
autoTranslate |
boolean |
false |
是否启用自动翻译（关闭后需手动点击翻译按钮） |
quantityTranslation |
number |
3 |
手动翻译模式下保留的翻译结果数量 |
includeContext |
boolean |
false |
翻译时是否携带光标附近的上下文代码 |
contextLines |
number |
5 |
携带上下文代码的行数（光标所在行前后各 contextLines / 2 行） |
maxContextLength |
number |
1000 |
携带上下文的最大字符数限制 |
startupDelay |
number |
3000 |
插件首次启动延迟时间（毫秒），该设置确保翻译内容始终在悬浮提示的最顶部显示，如果发现翻译结果在底部，则适当增加延迟时间 |
API 配置示例
阿里云百炼（默认）
魔搭社区（推荐，每天2000次免费调用）
智谱开发平台
深度求索（deepseek）
火山引擎（豆包系列）
OpenAI
- baseURL:
https://api.openai.com/v1
- model:
gpt-4o 或 gpt-3.5-turbo
本地 Ollama
- baseURL:
http://localhost:11434/v1
- model:
llama3 或其他本地模型
** 注意：接口需要支持openai格式，目前国内主流大模型厂商均支持该格式，建议使用非思考模型 **
💡 使用方法
基本使用
- 在代码文件中悬停鼠标到需要翻译的文本上
- 点击"翻译"按钮显示翻译（默认手动模式）或等待自动显示翻译结果（自动模式）
- 点击"重新翻译"按钮更新翻译结果
- 通过"禁用翻译"/"开启翻译"切换翻译功能状态
- （可选）启用上下文功能可在翻译时包含周围代码，提高准确性
缓存管理
- 使用
Ctrl+Shift+P 打开命令面板
- 搜索并执行"查看翻译缓存"
- 在缓存管理界面可以：
- 查看所有缓存的翻译结果
- 编辑翻译内容
- 删除单个缓存条目
- 清空全部缓存
提示词模板自定义
可以通过 promptTemplate 配置项自定义翻译提示词：
${content} - 原文内容占位符- 默认值：
简短解释一下，不要回复其他内容：${content}
- 例如：
请将以下代码注释翻译成中文：${content}
🛠️ 开发环境
先决条件
- Node.js (推荐 v18+)
- pnpm (推荐)
- VSCode
项目设置
# 克隆项目
git clone https://github.com/nihaozyj7/DocTranslate
# 进入项目目录
cd DocTranslate
# 安装依赖
pnpm install
# 编译项目
pnpm run compile
# 启动开发调试（按 F5）
# 或者监听编译
pnpm run watch
项目结构
src/
├── extension.ts # 插件入口点，激活和停用逻辑
├── hoverProvider.ts # 悬浮提供者，处理悬停事件和翻译显示
├── translation.ts # 翻译核心逻辑，API请求和错误处理
├── cache.ts # 缓存管理，包括过期清理和持久化
├── commands.ts # 命令定义，提供翻译开关等功能
├── types.ts # 类型定义
├── utils.ts # 工具函数，如MD5哈希、上下文提取等
└── views/
└── cacheView.ts # 缓存可视化管理界面
主要功能实现
- Hover翻译: 利用VSCode的Hover Provider API实现悬浮翻译
- 缓存机制: 使用MD5哈希作为键值缓存翻译结果，避免重复翻译
- 防抖处理: 防止重复请求和界面闪烁
- 状态管理: 使用globalState存储用户偏好和缓存数据
- 上下文提取: 提取光标附近代码上下文，提升翻译准确性
🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进项目：
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature)
- 提交更改 (
git commit -m 'Add some AmazingFeature')
- 推送到分支 (
git push origin feature/AmazingFeature)
- 创建 Pull Request
开发规范
- 使用 TypeScript 进行类型安全的开发
- 遵循 ESLint 代码规范
- 保持代码模块化和可维护性
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🐛 问题反馈
如果遇到问题或有建议，请在 GitHub Issues 中提交反馈。
DocTranslate © 2025 nihaozyj7. Released under the MIT License.
