使用 OpenAI 兼容的聊天补全接口（/v1/chat/completions），在 Visual Studio Code 与 Cursor 中翻译 Markdown。默认在新标签页打开译文，不修改源文件（可选原地替换）。
English: Translate Markdown via any OpenAI-compatible LLM API. Results open in a new editor tab by default; optional in-place replacement. Requires configuring mdTranslate.apiUrl and a model.
安装
- 在扩展视图中搜索 Markdown Translate 并安装；或
- 下载发行包中的
.vsix，执行 Extensions: Install from VSIX… 本地安装。
快速开始
- 打开 设置，搜索
Markdown Translate，填写mdTranslate.apiUrl（须为完整聊天补全地址，例如https://api.openai.com/v1/chat/completions）。 - 配置
mdTranslate.model（如gpt-4o-mini）。 - 使用 OpenAI 或需鉴权的网关时，在设置中填写
mdTranslate.apiKey，或运行命令 Markdown Translate: Set LLM API Key 将密钥存入本机 Secret Storage（推荐）。 - 打开任意
.md文件：用命令面板执行翻译命令，或点击源码首行 CodeLens「中↔EN」、标题栏图标、状态栏 「中↔EN」。
本地 Ollama 等无鉴权场景：将 mdTranslate.apiKeyOptional 设为 true，并可不保存 API Key。
功能概览
| 能力 | 说明 |
|---|---|
| 翻译选区或全文 | 有选区时翻译选区，无选区时翻译当前文档；大文档超过行数阈值会先提示确认。 |
| 译文输出位置 | 默认在新标签打开未命名 Markdown（首行 HTML 注释标明来源）；可将 resultDestination 设为原地替换。 |
| 双语言切换翻译 | 在 targetLanguage 与 secondaryTargetLanguage 之间轮换，每次在新标签输出译文（不修改原文）。 |
| CodeLens | 在 Markdown 源码首行显示「中↔EN」，点击即可切换翻译（运行于扩展宿主，稳定可靠）。 |
| 标题栏 / 状态栏 | 打开 Markdown 时显示切换翻译入口，与 CodeLens 使用同一套逻辑。 |
| 右键菜单 | 在 Markdown 编辑器中右键可调用翻译命令。 |
说明： 内置 Markdown 预览运行在 Webview 中，扩展无法在预览内稳定挂载可点的 vscode:// / command: 悬浮按钮；因此本扩展不提供预览内悬浮按钮，请使用源码 CodeLens 或标题栏 / 状态栏。
命令
| 命令 ID | 标题（命令面板中显示） |
|---|---|
mdTranslate.translate |
Markdown Translate: Translate Selection or Document |
mdTranslate.toggleTranslate |
Markdown Translate: Toggle language and translate (new tab) |
mdTranslate.codelensToggle |
Markdown Translate: Toggle (from CodeLens) |
mdTranslate.setApiKey |
Markdown Translate: Set LLM API Key |
设置（mdTranslate.*）
在设置 UI 中搜索 Markdown Translate 即可。
| 配置项 | 说明 |
|---|---|
apiUrl |
必填。聊天补全接口的完整 URL（含路径）。示例：https://api.openai.com/v1/chat/completions；Ollama：http://127.0.0.1:11434/v1/chat/completions。 |
apiKey |
可选。若填写，优先于 Secret Storage 中的密钥。勿将含密钥的 settings.json 提交到公开仓库。 |
model |
模型名称，如 gpt-4o-mini 或本地 Ollama 模型名。 |
targetLanguage |
翻译命令的默认目标语言描述，默认「简体中文」。 |
secondaryTargetLanguage |
与上一项配对，供「切换并翻译」轮换，默认 English。 |
sourceLanguage |
源语言提示（如 English）；留空则由模型判断。 |
resultDestination |
newEditor（默认）在新标签打开译文；replaceSelection 为原地替换选区或全文。切换翻译命令始终在新标签打开。 |
openTranslatedIn |
新标签打开译文时的列：beside（侧栏）或 active（当前列）。 |
showCodeLens |
是否在 .md 源码首行显示「中↔EN」CodeLens，默认 true。 |
chunkSize |
单次请求最大字符数；超出则分块串行请求。 |
temperature |
采样温度，默认 0.3。 |
apiKeyOptional |
true 时不强制填写 API Key（适用于本地无鉴权服务）。 |
confirmLargeDocumentLines |
整篇翻译且行数超过该值时先确认，默认 400。 |
隐私与安全
- 翻译内容会发送至你在
apiUrl中配置的远端服务（或本地 Ollama），请自行评估服务商隐私政策与合规要求。 - Set LLM API Key 将密钥写入本机 Secret Storage，不会写入工作区或普通
settings.json。 - 若使用设置中的
apiKey，请注意同步与备份范围，避免泄露。
环境要求
- VS Code
>= 1.85.0（或与之一致的 Cursor 版本）。
限制与免责声明
- 译文质量取决于模型与提示词； fenced 代码块、行内代码中的内容可能被误译，重要文档请先备份或使用版本控制。
- 长文会产生多次网络请求，受服务商速率与配额限制。
- 本扩展不内置任何大模型服务，亦不对第三方 API 的可用性、内容审查或计费负责。
从 DeepL 版迁移
本扩展仅支持 LLM；旧版 DeepL 密钥不再使用。请改用 Set LLM API Key（或 apiKey 设置），并配置完整 apiUrl 与 model。若曾使用 mdTranslate.apiBaseUrl，请改为 apiUrl，并在路径中保留 /chat/completions（例如 https://api.openai.com/v1 → https://api.openai.com/v1/chat/completions）。
开发与打包
维护者克隆本仓库后，在扩展根目录执行：
npm install
npm run compile
使用 F5 启动 Extension Development Host 调试。发布前打包：
npm run compile
npx @vscode/vsce package
生成 md-translate-<version>.vsix（版本见 package.json）。
若仓库位于 monorepo 子目录，请先 cd 到扩展根目录再执行上述命令。
许可证
本项目以 MIT License 发布，详见仓库中的 LICENSE 文件。