wangzhy Translation

把 TranslationPlugin 的常用操作移植到 VS Code，仅使用 OpenAI / OpenAI 兼容 API。

重点是三件事：AI 翻译、方法注释正文翻译、选中文字后弹出译文。默认目标语言为简体中文，只有主动触发翻译才会请求 API。

翻译提示词要求按上下文使用自然表达，避免逐词直译和照搬原文语序。中文优先使用简洁、通顺的技术表述，保留条件、否定和行为限制；方法文档保留代码与参数名，单词和短语只给出简明译法。

安装与配置

1. 在 VS Code 扩展面板搜索 wangzhy.wangzhy-translation，或从 Visual Studio Marketplace 安装。也可以在扩展面板的 … 菜单中选择 从 VSIX 安装…，选择 wangzhy-translation-0.1.10.vsix。升级后执行 Developer: Reload Window（开发人员: 重新加载窗口），启用新版本。
2. 打开命令面板，执行 Translation: 配置 OpenAI API…。
3. 依次填写 API 地址、模型 ID、API Key。默认地址为 https://api.openai.com/v1，默认模型为 gpt-4o-mini；使用兼容服务时填写该服务提供的模型 ID。

API Key 保存在 VS Code SecretStorage，不写入 settings.json，不发送给网页界面。Key 按服务源（协议、主机、端口）隔离；切换服务源后，需要为新服务单独配置 Key。可通过命令设置或删除当前服务的 Key。

地址接受以下形式：

仅使用 Chat Completions 协议。不会自动探测模型、重试收费请求或跟随 HTTP 重定向。地址需指向最终接口。本地兼容服务无需鉴权时，可以关闭 wangzhyTranslation.openai.requireApiKey。

最常用的两个操作

翻译方法注释

把鼠标移到方法名上，让 VS Code 显示原始文档，再直接按 F10，无需点击弹框或选中文字，光标停在其他位置或空行也可以。macOS、Windows 和 Linux 使用同一快捷键。有明确选区时优先翻译选区。

按键后立即显示并聚焦该位置的原生悬浮框，框内显示旋转等待图标及“正在翻译…（F10 取消）”，方法原文继续可读。完成后等待状态替换为译文；取消或失败时清除等待状态。翻译过程不再显示右下角的进度通知，独立翻译窗口使用自身的进度状态。

将说明正文及其中的示例代码发送给模型，翻译自然语言说明并要求保留代码；排除正文前的类型/方法声明、Go 版本说明和独立导航链接。译文中的示例按原顺序穿插在对应的说明段落之间，以代码块显示并保留缩进、语法高亮。例如 time.Second 的除法、乘法示例都会出现在中文说明下方。

原生悬浮框中增加 中文译文，语言扩展的原始文档继续保留。VS Code 会合并多个扩展的 Hover 内容，公开 API 无法覆盖其他扩展的原文，因此方法注释暂时保留原文。也可以点击“翻译方法注释”触发；源码或注释不会被修改。

在同一方法上再次按 F10，移除译文，恢复原始方法文档。恢复不请求 API；再按一次可使用缓存重新显示译文。

该功能读取语言扩展提供的 Hover 文档，因此 Java、Python、C# 等语言需要先安装能显示原始方法文档的相应扩展。VS Code 内置 JavaScript / TypeScript 已支持。“翻译方法注释”命令在没有可翻译正文时静默结束。

VS Code 公共 API 只能在光标处重新打开悬浮框。如果鼠标指向的方法与光标不在同一处，快捷键会把光标定位到所悬浮的方法，以显示原文和译文。它不会修改文件。

VS Code 会先关闭未聚焦悬浮框再执行 F10 命令，扩展随后立即重开并聚焦；首次按键和内容刷新时可能短暂闪动，API 等待期间保持框内等待状态。

翻译选中文字

选中一句话、一段注释或多行文字，然后按 F10。保留同一选区再次按 F10，关闭译文并恢复原状；文件内容和选区保持不变。改选其他文字后按 F10，则翻译新选区。

在原文位置弹出 VS Code 原生悬浮框，插件只显示 中文译文，不再重复展示选中的原文；不会替换文件内容。支持复制译文和手动打开独立对照窗口。按 Esc 关闭；再次悬浮原文可查看当前会话中的译文。没有选区时，自动获取光标处单词或完整标识符，getUserName 会作为 get user name 翻译。

译文保留分段，并允许文字随宽度自然折行。翻译完成后重新打开悬浮框，由 VS Code 根据内容自动布局；宽高上限仍由编辑器控制，扩展不设置固定尺寸。Hover API 说明

悬浮框和独立对照窗口中的译文使用柔和的鼠尾草绿，便于与原文区分：深色主题为 #8FBC9B，浅色主题为 #3E7A54，高对比度主题使用对应的高对比配色。悬浮译文中的示例代码保留语法高亮。

等待方法文档或 API 返回时，再按 F10 会取消当前翻译；晚到的结果不会重新弹出。新请求会取消旧请求；原文件在等待期间发生变化时，不会把旧结果显示在新内容上。切换只隐藏当前位置的译文，保留其他位置的译文和缓存。

移动光标、改变选区、修改文件、切换编辑器或滚动后，不再使用此前悬浮的方法位置。悬浮普通单词没有方法说明时，F10 翻译该单词。

没有可翻译内容时（如空行、纯空白选区或未打开文本编辑器），翻译操作静默结束，不显示提示、翻译进度或请求 API。API 配置和请求错误仍会正常提示。

其他保留的操作

翻译与恢复统一使用 F10，已移除原来的翻译快捷键；其他操作保留上表中的组合。F10 在编辑器或悬浮框中生效，会占用该上下文中的原有按键用途（例如调试的单步跳过）。可在“键盘快捷方式”中搜索 wangzhyTranslation 修改。

独立窗口支持输入文字、切换语言、交换原文译文、Cmd/Ctrl + Enter 翻译。历史默认保留最近 50 条，可以设为 0 清空并关闭。

“翻译并替换”默认把中文译为英文，英文译为默认目标语言。英文短语提供 camelCase、PascalCase、下划线、连字符等候选；选择候选后才替换，并支持一次撤销。翻译后文件变化会拒绝替换，避免写错位置。该操作一次支持一个选区。

未移植 TTS、单词表、每日单词、多翻译引擎切换，以及 JetBrains 专有的内联文档渲染与批量操作。

常用设置

{
  "wangzhyTranslation.openai.baseUrl": "https://api.openai.com/v1",
  "wangzhyTranslation.openai.model": "gpt-4o-mini",
  "wangzhyTranslation.targetLanguage": "zh-CN",
  "wangzhyTranslation.openai.timeoutSeconds": 60,
  "wangzhyTranslation.autoSelectionMode": "inclusive",
  "wangzhyTranslation.splitIdentifiers": true,
  "wangzhyTranslation.keepFormat": true,
  "wangzhyTranslation.historySize": 50
}

API 地址、模型和鉴权开关仅接受用户级设置，工作区不能覆盖这些设置。默认每次最多发送 20,000 字符，可通过 maxInputLength 调整。

仅发送本次选择或获取的文档文本，不发送整个项目。历史原文和译文以明文保存在扩展宿主的本地存储中，不加入 Settings Sync；可以关闭历史或使用清空命令。API Key 使用独立的安全存储。Remote SSH / Dev Container 下，请求由远端扩展宿主发出，API 地址须能从远端访问。

开发与验证

需要 Node.js 22+，VS Code 1.100+。

npm ci
npm test
npm run test:integration
npm run package

按 F5 启动扩展开发宿主。集成测试默认使用 @vscode/test-electron 下载 VS Code，也可通过 VSCODE_EXECUTABLE_PATH 指定已有的 VS Code 可执行文件。测试使用临时独立用户配置与本机 mock API，不读取个人 Key，不调用付费 API，不修改日常 VS Code 配置。

macOS 使用本机 VS Code 的示例：

VSCODE_EXECUTABLE_PATH="/Applications/Visual Studio Code.app/Contents/MacOS/Code" npm run test:integration

单元测试覆盖文档正文过滤、取词、标识符拆分、替换格式、地址解析、实际 HTTP 请求、取消、超时和错误响应；集成测试在真实扩展宿主中验证未点击悬浮框且光标位于空行时的翻译、旧悬浮位置失效、F10 显示与恢复、等待期间重复按键取消、选区只显示译文、Go 文档请求范围、自然换行的 Markdown 输出、鼠标位置取文档、内置 TypeScript 方法文档、并发取消、过期选区保护与撤销。

发布到 Marketplace 使用发布者 wangzhy。首次发布需在本机终端运行 npx vsce login wangzhy 完成登录；更新版本及 CHANGELOG.md、验证通过后执行 npm run publish:marketplace。凭据由 vsce 管理，不写入工程文件。private: true 防止误发到 npm，不影响扩展市场发布。

来源与许可

原项目：YiiGuxing/TranslationPlugin，参考版本 bb50b0f4debe5464ffe99ede63c95e5456862bb7，MIT 许可。取词、替换候选与命令交互参考了原项目，VS Code 实现使用 TypeScript 重写。原作者许可声明保留在 LICENSE 中，本项目为独立移植。

接口依据：OpenAI Chat Completions；扩展接口依据：VS Code API。