Translate Inline Preview

在 VS Code 中为中文开发者提供 英文 → 中文 的实时代码注释 / 文档翻译预览。支持多种在线翻译后端，可插拔切换

Translate Inline Preview renders real-time translations of English code comments and documents directly in the editor — above the paragraph (CodeLens) or on hover — with full-text side-by-side comparison panels. Backends are pluggable: Aliyun, Baidu, Google, Youdao, Tencent, DeepL, or any OpenAI-compatible endpoint, chained with automatic failover, retries and circuit breaking via a declarative providers.json.

功能

• 实时翻译预览：在英文段落（注释、文档、Markdown、YAML 值等）上方或悬停时渲染中文译文
• 三种查看方式：
  • overhead（默认）：段落上方用 CodeLens 显示独立一行的译文，自动内联渲染；
  • hover：悬停时光标所在段落才显示译文，不打断正文；
  • 显式 Webview 对照（按需触发）：点击 CodeLens、悬停查看全文 tooltip，或执行 Show Full Translation / Compare View 命令，以侧边 Webview 面板展示完整原文 + 译文（含质量分）
• 多供应商容错调用链：通过 providers.json 自定义主备 / 重试 / 负载轮询，防止单点 API 异常导致翻译中断
• 支持的翻译后端：Aliyun、Google、Youdao、Baidu、DeepL、Tencent，以及自定义 OpenAI 兼容 HTTP 引擎
• 免费额度兜底链：默认阿里云 → 百度 → 腾讯云，额度用尽自动切换其他供应商，无需付费即可持续翻译
• 扩展能力：L3 翻译记忆库（跨会话复用）、L2.5 精确缓存（导入 / 导出）、项目术语库（术语一致）、用量统计与配额自动停用、批量翻译队列、原文 / 译文 / 质量对照预览

快速开始

1. 安装插件（.vsix 或通过扩展面板）

2. 声明供应商与容错链：在工作区 .vscode/providers.json 中配置。命令 Translate Inline Preview: Generate providers.json Template 可一键生成模板，最小配置如下。密钥统一用 ${ENV_VAR} 占位符，不要直接写进文件

   {
     "version": 1,
     "chains": [
       {
         "id": "default",
         "strategy": "failover",
         "providers": [ "aliyun", "baidu", "tencent" ],
         "retry": { "maxAttempts": 2, "baseDelayMs": 300, "maxDelayMs": 5000 },
         "maxRateLimitWaitMs": 8000
       }
     ],
     "providers": [
       { "id": "aliyun", "type": "aliyun", "monthlyCharLimit": 1000000,
         "credentials": { "accessKeyId": "${ALIYUN_ACCESS_KEY_ID}", "accessKeySecret": "${ALIYUN_ACCESS_KEY_SECRET}" } },
       { "id": "baidu", "type": "baidu",
         "credentials": { "appid": "${BAIDU_APP_ID}", "apiKey": "${BAIDU_KEY}" } },
       { "id": "tencent", "type": "tencent",
         "credentials": { "secretId": "${TENCENT_SECRET_ID}", "secretKey": "${TENCENT_SECRET_KEY}" } }
     ]
   }
   

   阿里云优先（免费 100 万字符 / 月），额度耗尽自动 failover 到百度，再到腾讯云兜底，全程无需付费

3. 设置密钥变量（两种方式任选其一，值均从对应云厂商控制台获取）：

   方式 A — 系统环境变量（推荐，所有项目通用）：

   # Windows (PowerShell)
   [Environment]::SetEnvironmentVariable("ALIYUN_ACCESS_KEY_ID", "你的阿里云AccessKeyId", "User")
   [Environment]::SetEnvironmentVariable("ALIYUN_ACCESS_KEY_SECRET", "你的阿里云AccessKeySecret", "User")
   [Environment]::SetEnvironmentVariable("BAIDU_APP_ID", "你的百度AppId", "User")
   [Environment]::SetEnvironmentVariable("BAIDU_KEY", "你的百度API Key", "User")
   [Environment]::SetEnvironmentVariable("TENCENT_SECRET_ID", "你的腾讯云SecretId", "User")
   [Environment]::SetEnvironmentVariable("TENCENT_SECRET_KEY", "你的腾讯云SecretKey", "User")
   

   # macOS / Linux
   export ALIYUN_ACCESS_KEY_ID="你的阿里云AccessKeyId"
   export ALIYUN_ACCESS_KEY_SECRET="你的阿里云AccessKeySecret"
   export BAIDU_APP_ID="你的百度AppId"
   export BAIDU_KEY="你的百度API Key"
   export TENCENT_SECRET_ID="你的腾讯云SecretId"
   export TENCENT_SECRET_KEY="你的腾讯云SecretKey"
   

   方式 B — VS Code 设置（仅本机本扩展生效）：在 settings.json 中加入

   {
     "translateInlinePreview.ALIYUN_ACCESS_KEY_ID": "你的阿里云AccessKeyId",
     "translateInlinePreview.ALIYUN_ACCESS_KEY_SECRET": "你的阿里云AccessKeySecret",
     "translateInlinePreview.BAIDU_APP_ID": "你的百度AppId",
     "translateInlinePreview.BAIDU_KEY": "你的百度API Key",
     "translateInlinePreview.TENCENT_SECRET_ID": "你的腾讯云SecretId",
     "translateInlinePreview.TENCENT_SECRET_KEY": "你的腾讯云SecretKey"
   }
   

   变量名需与 providers.json 中 ${...} 占位符一一对应（如 ${ALIYUN_ACCESS_KEY_ID} 对应 ALIYUN_ACCESS_KEY_ID）。不要把密钥写进仓库，也不要在 providers.json 里写明文（明文仅 debugAllowPlaintextCredentials 开发开关下允许）

4. 打开含英文注释 / 文档的文件，译文即按 displayMode（默认 overhead）出现在段落上方，或悬停显示

效果演示

悬停预览（hover 模式）

将 translateInlinePreview.displayMode 设为 hover 后，鼠标悬停在英文段落上即可看到中文译文，不打断正文阅读：

全文对照 Webview

点击 CodeLens 或执行 Translate Inline Preview: Show Full Translation 命令，会以模态框 / 侧边 Webview 展示完整原文与译文对照：

具体示例

示例 1：代码注释 / 文档实时翻译（overhead 模式，默认）

overhead 模式在英文段落 上方 渲染独立一行的 CodeLens 译文，适合需要独占一行对照的场景（代码注释、.md、JSDoc 文档等）。默认即开，也可在 settings.json 中显式配置并调小 codeLensMaxLength：

{
  "translateInlinePreview.displayMode": "overhead",
  "translateInlinePreview.codeLensMaxLength": 80
}

应用后，段落上方会出现一行 CodeLens 译文，超长自动截断为 …，悬停看完整 tooltip，点击打开全文。代码注释与 Markdown 文档表现一致：

// ╭─ 初始化应用上下文并注册所有核心服务｜配置文件缺失或格式错误时抛出 ─╮  ← CodeLens 译文（段落上方）
/**
 * Initializes the application context and registers all core services.
 * Throws if the configuration file is missing or malformed.
 */
function bootstrap() { /* ... */ }

╭─ 初始化应用上下文并注册所有核心服务｜配置缺失或格式错误时抛出 ─╮  ← CodeLens 译文（段落上方）
# Initializes the application context and registers all core services.
# Throws if the configuration file is missing or malformed.

文档其余正文……

示例 2：免费零成本翻译链路（推荐新手）

在 .vscode/providers.json 中声明容错链（密钥通过 ${ENV_VAR} 占位符提供，详见上文）：

{
  "version": 1,
  "chains": [
    {
      "id": "free",
      "strategy": "failover",
      "providers": [
        { "id": "aliyun" },
        { "id": "baidu" },
        { "id": "tencent" }
      ]
    }
  ],
  "providers": [
    { "id": "aliyun", "type": "aliyun", "monthlyCharLimit": 1000000,
      "credentials": { "accessKeyId": "${ALIYUN_ACCESS_KEY_ID}", "accessKeySecret": "${ALIYUN_ACCESS_KEY_SECRET}" } },
    { "id": "baidu", "type": "baidu",
      "credentials": { "appid": "${BAIDU_APP_ID}", "apiKey": "${BAIDU_KEY}" } },
    { "id": "tencent", "type": "tencent",
      "credentials": { "secretId": "${TENCENT_SECRET_ID}", "secretKey": "${TENCENT_SECRET_KEY}" } }
  ]
}

• 阿里云优先（免费 100 万字符 / 月），额度耗尽自动切换百度 / 腾讯云兜底，翻译不中断
• Youdao（无需密钥）等其他端点也可作为额外兜底，按需加入链中

腾讯云 TMT（tencent）当前仍是可用后端，需在 providers.json 中声明并通过 ${TENCENT_SECRET_ID} / ${TENCENT_SECRET_KEY} 提供密钥（限流建议 2/3，低于免费版 5/s 硬配额）

调用链路原理

chains: free = failover [ aliyun → baidu → tencent ]
        │
        ├─① 阿里云（主引擎，免费 100 万字符/月，需 ${ALIYUN_ACCESS_KEY_ID} / ${ALIYUN_ACCESS_KEY_SECRET}）
        │      ├─ 成功            → 返回译文
        │      └─ 额度耗尽/失败   → 自动进入②
        │
        ├─② 百度（兜底，需 ${BAIDU_APP_ID} / ${BAIDU_KEY}）
        │      └─ 成功 → 返回译文
        │
        └─③ 腾讯云（末位兜底，需 ${TENCENT_SECRET_ID} / ${TENCENT_SECRET_KEY}）
               └─ 返回译文（或全部失败时才提示）

阿里云免费额度用尽后，Router 会 静默 切换到下一个供应商继续翻译，默认不打扰你。若希望感知切换，将 translateInlinePreview.notifyOnFallback 设为 true：开启后整个会话 仅弹一次 info 提示；若所有供应商均失败，才按 60 秒节流弹出失败告警

示例 3：显式全文对照（Webview，任何模式下可用）

overhead / hover 只渲染片段译文；需要看 完整原文 + 译文（+ 质量分） 时，用显式方式打开 Webview 面板（侧边栏，独立于编辑器、不会被重绘关闭）：

• 点击 overhead 模式下的 CodeLens → 触发 Translate Inline Preview: Show Full Translation；
• 或执行命令 Translate Inline Preview: Show Full Translation（直接打开译文面板）；
• 或执行 Translate Inline Preview: Compare View (原文/译文/质量) → 打开原文 / 译文 / 质量分三栏对照面板

// ╭─ Initializes the application context and registers all core services ─╮  ← 点击它
/**
 * Initializes the application context and registers all core services.
 * Throws if the configuration file is missing or malformed.
 */
function bootstrap() { /* ... */ }

打开的侧边 Webview（见 效果演示）完整展示原文与译文，长文不截断，便于校对与复制

多供应商容错调用链（Router）

翻译由一个可配置的 Router（借鉴 litellm 思路）按照 providers.json 编排：

• 调用链策略（strategy）：
  • failover：按顺序逐一尝试，遇到成功即返回；
  • round_robin：每次轮换到下一个健康供应商，均匀分摊；
  • weighted：按权重选择（如阿里云 3 / DeepL 2 / 百度 1）
• 重试与退避：对 timeout / server / network / rate_limit 类错误按指数退避重试；quota / auth 类错误 不重试，直接换供应商或报错
• 三态熔断：每个供应商有 closed → open → half_open 熔断器，连续 5 次可重试失败后断路 30s，避免对故障供应商持续打流量
• 速率限制：每个供应商可在 providers.json 中声明 rateLimit: { ratePerSec, burst }，Router 据此做令牌桶限流（以 providers.json 为准，不再硬编码）
• 结构化错误：所有供应商统一抛 TranslationError，由 Router 据此分类决策

providers.json 示例

放在工作区 .vscode/providers.json（可用命令 Translate Inline Preview: Generate providers.json Template 一键生成）：

{
  "version": 1,
  "chains": [
    {
      "id": "primary",
      "strategy": "failover",
      "providers": [
        { "id": "aliyun" },
        { "id": "baidu" },
        { "id": "tencent" }
      ],
      "retry": { "maxAttempts": 2, "baseDelayMs": 300, "maxDelayMs": 5000 }
    },
    {
      "id": "balanced",
      "strategy": "weighted",
      "providers": [
        { "id": "aliyun", "weight": 3 },
        { "id": "deepl", "weight": 2 },
        { "id": "baidu", "weight": 1 }
      ],
      "retry": { "maxAttempts": 2 }
    }
  ],
  "providers": [
    {
      "id": "aliyun",
      "type": "aliyun",
      "monthlyCharLimit": 1000000,
      "rateLimit": { "ratePerSec": 5, "burst": 10 }
    },
    {
      "id": "baidu",
      "type": "baidu",
      "monthlyCharLimit": 0,
      "rateLimit": { "ratePerSec": 5, "burst": 10 },
      "credentials": { "appid": "${BAIDU_APP_ID}", "apiKey": "${BAIDU_KEY}" }
    },
    {
      "id": "tencent",
      "type": "tencent",
      "monthlyCharLimit": 0,
      "rateLimit": { "ratePerSec": 5, "burst": 10 },
      "credentials": { "secretId": "${TENCENT_SECRET_ID}", "secretKey": "${TENCENT_SECRET_KEY}" }
    },
    {
      "id": "deepl",
      "type": "deepl",
      "monthlyCharLimit": 500000,
      "credentials": { "authKey": "${DEEPL_AUTH_KEY}" }
    }
  ]
}

修改后 热重载，无需重启扩展。providers.example.json 是提交到仓库的模板，请勿把真实凭据写进它

字段说明

type 支持的枚举（以 src/config/providers-config.ts 的 PROVIDER_TYPES 为准）：aliyun / google / youdao / baidu / deepl / tencent / custom / openai_compatible。Azure、Caiyun、Volcengine 等不在此列表中的类型请改用 openai_compatible 自定义实现（见 providers.example.json 的 deepseek / caiyun 示例）

配置项

在 VS Code settings.json 中配置：

说明

• codeLensMaxCount 未在 package.json 的 contributes.configuration 中注册，由代码默认值与 clamp 提供；settings.json 中可手动写入但不带编辑器提示
• 旧版单供应商密钥配置项（如 aliyunAccessKeyId / baiduAppId / tencentSecretId / deeplAuthKey）已从 package.json 移除；当前统一在 .vscode/providers.json 中声明供应商，密钥通过 ${ENV_VAR} 占位符提供（详见文末「安全说明」）
• 旧版单供应商选择器 translateInlinePreview.translationProvider 已废弃、无效果（保留仅为向后兼容字段名）。请改用 providers.json 配置容错链

语言与分拣

sourceLanguage / targetLanguage 决定翻译方向，并驱动门卫与分拣：

• 门卫（Guard）：文本脚本与目标语言脚本一致才进入翻译（目标 zh-CN 时仅英文段落），已在目标语言中的同质段直接短路；防御性检查对 source/target 做 canonical 归一后相同时，仍按文本脚本二次判断，避免配置相等却误伤另一语种文本
• 三段式分拣（segmentTranslatable）：mask → translate → restore 三段流水。先保护格式占位符（F，代码块 / URL / 公式等）与术语占位符（G）；再识别对照段——中文…（English）（A 型）与 中文 / English（B 型）——用 S 占位符替换，只翻译中文侧、保留英文侧原样；最后还原全部占位符。S / F / G 三层占位符互不串位
• 互斥回退：sourceLanguage 与 targetLanguage 相同（canonical 归一后）时自动回退——目标为 en 时回退 zh-CN，否则回退 en；Set Source Language 命令的候选列表会隐藏与目标相同的语言，状态栏提示冲突
• protectParallelText（默认开）：对照段保护总开关。关闭后对照段中的英文侧也会被整体翻译（旧行为）

语种矩阵

被拒语对统一抛 unsupported 错误：不参与重试 / 熔断计数，Router 自动 failover 到链中下一家，不会静默产出错误语种的译文

overhead 模式长译文处理

CodeLens 标题受 VSCode API 限制只能渲染单行，超长时会被视口截断，本插件采用业界通用做法（与 GitLens / i18n CodeLens 一致）：

• 标题截断：超过 translateInlinePreview.codeLensMaxLength 的译文以 … 结尾，保证单行可读；
• 悬停 tooltip：鼠标悬停显示完整「原文 + 译文」，支持换行；
• 点击看全文：点击 CodeLens 触发 translateInlinePreview.showFullTranslation，以模态框展示完整原文与译文

overhead 模式（默认）用 CodeLens 在段落上方保留真正的一行，适合需要独占一行的对照场景；hover 模式则在悬停时才显示译文，不打断正文阅读。无论哪种 displayMode，都可以通过点击 CodeLens、悬停看全文 tooltip，或执行 Translate Inline Preview: Show Full Translation / Compare View 命令，显式打开侧边 Webview 面板查看完整原文 + 译文（及质量分）对照——这是第三种按需查看方式，不随 displayMode 关闭

命令

开关与作用范围

• Translate Inline Preview: Enable / Disable — 总开关：关闭后整个扩展不再渲染任何译文（优先级最高，覆盖一切）
• Translate Inline Preview: Scope Mode: Global / Scoped — 作用范围开关（对应配置 translateInlinePreview.scopeMode，取值 global / scoped）：总开关开启时生效。Scoped = 只翻译已加入 Scope 的文件；Global = 翻译工作区所有文件（覆盖 Scope 设置）
• Translate Inline Preview: Add Current File to Scope — 将当前文件加入作用范围
• Translate Inline Preview: Remove Current File from Scope — 将当前文件移出作用范围
• Translate Inline Preview: Add Current Folder to Scope — 将当前文件夹加入作用范围
• Translate Inline Preview: Remove Current Folder from Scope — 将当前文件夹移出作用范围
• Translate Inline Preview: Add Glob Pattern to Scope — 添加通配符作用范围
• Translate Inline Preview: Remove Glob Pattern from Scope — 移除通配符作用范围
• Translate Inline Preview: Show Scope Status — 查看当前作用范围配置
• Translate Inline Preview: Clear All Scopes — 清空所有作用范围

查看与对照

• Translate Inline Preview: Show Full Translation — 对光标所在（或点击 CodeLens 的）段落打开完整原文 + 译文 Webview 面板
• Translate Inline Preview: Compare View (原文/译文/质量) — 对光标所在段落打开原文 / 译文 / 质量分对照面板
• Translate Inline Preview: Batch Translate Document — 以受限并发批量翻译当前文档全部英文段落

配置与模板

• Translate Inline Preview: Generate providers.json Template — 生成 .vscode/providers.json 起始模板
• Translate Inline Preview: Open providers.json — 打开（必要时生成）providers.json
• Translate Inline Preview: Set Target Language — 从预设语言列表（9 种）中选择目标语言并写入全局设置，立即生效
• Translate Inline Preview: Set Source Language — 从预设语言列表中选择源语言（与目标语言互斥：候选列表隐藏与目标相同的语言，相同则自动回退）
• Translate Inline Preview: Mark Selection as Untranslated — 将选中文本写入项目术语库（原文→原文），之后该文本不再被翻译

缓存与统计

• Translate Inline Preview: Clear Translation Memory — 清空本地翻译记忆库（L3）
• Translate Inline Preview: Clear Precise Cache (L2.5) — 清空精确缓存
• Translate Inline Preview: Export Precise Cache — 导出精确缓存
• Translate Inline Preview: Import Precise Cache — 导入精确缓存
• Translate Inline Preview: Show Usage Stats — 查看各供应商当月字符用量与停用状态
• Translate Inline Preview: Show Translation Stats — 查看翻译命中率、缓存 / 记忆命中、耗时等运行统计

扩展能力

L3 翻译记忆库

把译过的段落按相似度（n-gram Jaccard ≥ 0.85）存到本地，下次遇到近乎相同的文字直接复用，省去重复联网翻译。可用 translateInlinePreview.enableTranslationMemory 关闭，或用 Translate Inline Preview: Clear Translation Memory 清空

L2.5 精确缓存

对 逐字相同 的原文做内存级缓存（仅限本次会话），命中率比 L3 更高，但不跨会话保留。支持用 Export / Import Precise Cache 命令导出 / 导入

L2.5 与 L3 的关系

两者都是「免联网复用已有译文」的缓存，但层级不同、互补：

• L2.5 精确缓存（快、短命）：要求原文 逐字一致 才命中，存在内存里、只活在当前会话。它最快，但换个会话或重启就清空
• L3 翻译记忆库（慢一点、长久）：按 相似度（Jaccard ≥ 0.85）匹配，存到本地磁盘、跨会话乃至跨项目保留。新会话里第一次遇到相近文字，就靠它免去联网

协作顺序：一段原文进来，先查 L2.5（精确命中就直接返回）；未命中再查 L3（相似命中同样复用）；都未命中才真正调用翻译，并把结果同时写回 L2.5 与 L3。因此 L2.5 像「手边的便签」，L3 像「归档的笔记本」——前者加速当下，后者沉淀历史

项目术语库

在工作区 .vscode/glossary.json 中登记术语对照，例如 { "source": "Kubernetes", "target": "Kubernetes" }。翻译时会先把术语替换成占位符、译完再还原，避免专业词被机翻改坏

用量统计与配额管控

在 providers.json 里给每个供应商设 monthlyCharLimit。当月累计用量超限时，该供应商会被 自动停用（Router 不再选它）并提示一次，防止意外超额。这是配置级管控，不绑定账号体系

格式保护与质量评分

• FormatPreserver：翻译前先把代码块、Markdown 围栏 / 链接、HTML 标签、URL、环境变量、@mention、#tag、行内公式 $...$、邮箱、emoji、转义符等用占位符保护起来，译完再还原；万一还原失败也有兜底，避免占位符残留在译文里
• QualityGate：每条译文都会打分，低于 translateInlinePreview.qualityThreshold 的不展示（对照面板会显示具体分数）。评分会拦截以下几类低质译文：
  • 中文占比不足
  • 原样回显（原文含中文却与译文完全相同）
  • 三明治结构（首尾是原文、中间夹中文）
  • 长度偏差过大（与原文长短比不合理）
  • 纯符号噪声（几乎全是标点 / 符号）
  • 中英文碎片交替（内部频繁穿插）

最佳实践

1. 新手直接用 providers.json 配置容错链：配好密钥后无需关心额度耗尽，翻译不中断
2. 按需选择展示模式（默认 overhead）：
   • overhead（默认）：独占一行 CodeLens，适合文档 / Markdown 对照、需要真正一行译文
   • hover：悬停才显示，适合需要干净正文的场景
3. 长译文用 overhead + 截断：把 codeLensMaxLength 调到合适值，避免单行过长；用悬停 tooltip 看全文
4. 密钥安全：密钥通过 providers.json 的 ${ENV_VAR} 占位符提供，仅存于本机 settings.json，不入库。详见文末「安全说明」
5. 限定作用范围：用 Add / Remove File / Folder / Glob Scope 只对需要的文件启用，减少无关翻译、节省额度
6. 关注质量阈值：通过 translateInlinePreview.qualityThreshold（默认 0.6）过滤低质量译文，避免噪声
7. 感知切换：将 translateInlinePreview.notifyOnFallback 设为 true，额度切换时弹一次提示，便于感知兜底生效
8. 关闭不需要的翻译：translateCodeComments（默认开）/ translateYamlValues（默认开）可按需开关

安全说明

• 所有云厂商密钥均从 settings.json 读取，仅本机 settings.json，不入库、不硬编码
• 凭据优先使用 providers.json 的 ${ENV_VAR} 占位符（读环境变量或仅本机 settings.json），明文仅在 debugAllowPlaintextCredentials 开启时允许（默认关闭）
• 翻译走 HTTPS，文本仅发送至你配置的翻译服务商