Markdown Bilingual Sync

在 VS Code 中翻译 Markdown，并以双语预览阅读；原文是唯一事实源，手动修改的译文会自动锁定，不会被静默覆盖。

当前版本为 Phase 3 完成版本，UI 为中文，支持本地 VSIX 安装与从源码构建。

功能

• 以顶层语义块为翻译单元：标题、段落、整段列表、整张表格、整段引用。
• 双语 Webview 预览：并排、交错与真正的左右分栏布局，分栏模式支持两个独立滚动窗格和块级滚动同步；支持 GFM、代码高亮、KaTeX、脚注和 GitHub Alerts。
• 同时支持 Markdown 与 Qoder 等环境提供的 skill 语言 ID（文件内容仍为 Markdown）。
• 可切换的 OpenAI 兼容或通用 HTTP 翻译服务，API Key 只保存在 VS Code SecretStorage；内置常用服务预设。
• 导入已有译文：按顶层块结构校验并对齐，全部标记为译文锁定；预览工具栏和命令面板都可发起导入。
• 缓存清理：可清理当前文件缓存，或一键清除扩展存储中的所有译文缓存。
• 批量处理：目录批量翻译按 token 预算动态分批，文件级与文件内批次共享并发上限；失败时保留已成功译文，也可批量导出已有缓存。
• 右侧翻译任务面板：状态栏右侧按钮切换右侧辅助侧边栏中的常驻 WebviewView，展示批量总览、文件明细、历史错误和运行状态。
• 批量翻译与增量同步：保存原文只标记过期，只有手动命令才请求翻译 API。
• 译文锁定：编辑译文缓存并保存后，该块不会被自动重译覆盖。
• 预览内编辑：点击原文或译文内容即可就地编辑原始 Markdown；译文保存后立即锁定，原文修改暂存后可先查看差异再写回源文件。
• 回译改写原文：对已有译文的块执行反向翻译，结果直接进入原文暂存；写回后该块译文锁定到新的原文，不会被同步覆盖。
• 稳定翻译：重新翻译参考旧译文，回译参考当前原文，减少细微修改造成的措辞波动；设置与预览开关均可控制。
• 全文摘要：手动生成原文语言摘要，作为同步/重译/回译的上下文；摘要随译文缓存保存，可在预览中查看、编辑、清除。
• 单块重译、过期块重译、全部机器译文重译。
• 全局术语表与标题上下文增强。
• 导出到同目录语言后缀文件，写入前显示分栏差异确认。
• 导出/重译前可发现结构问题；AI 返回提示词、请求回显或未翻译原文时拒绝写入缓存。

安装

code --install-extension artifacts/vsix/markdown-bilingual-sync.vsix

需要 VS Code 1.90 或更高版本（扩展使用 Webview、SecretStorage 与 WorkspaceEdit）。

从源码构建

需要 Node.js 20 或更高版本：

git clone https://github.com/yxm1122/Markdown-Bilingual-Sync.git
cd Markdown-Bilingual-Sync
npm ci
npm run package

构建产物位于 artifacts/vsix/markdown-bilingual-sync.vsix，可按上面的安装命令安装。开发调试可直接在 VS Code 中按 F5 启动扩展开发主机；详细命令见“开发”一节。

快速开始

1. 打开一个已保存到磁盘的 .md 文件。
2. 在设置中确认语言对，默认 en → zh-CN。
3. 执行命令 Markdown Bilingual Sync: 设置 AI 翻译 API Key，粘贴密钥。
4. 在设置中选择翻译服务，或执行 应用翻译服务预设…：
   • markdownBilingualSync.provider 设为 openai
   • markdownBilingualSync.apiBaseUrl 如 https://api.openai.com/v1
   • markdownBilingualSync.apiModel 如 gpt-4o-mini
   • 或设为 http，配置 httpEndpoint、httpHeaders、httpBody、httpResponsePath
5. 执行 Markdown Bilingual Sync: 测试 AI 翻译连接，确认接口、模型/模板和密钥可用。
6. 执行 翻译当前文件，双语预览会在当前编辑器组中以新标签页打开，不会自动切开编辑器窗口。
7. 之后修改原文并保存，执行 同步译文 只翻译缺失或过期块。
8. 已有译稿可点击预览工具栏 导入译文（或命令面板 导入已有译文…）导入为译文锁定块。

工作流与语义

原文为准

• 原文默认不会被自动改写；只有显式执行原文编辑、删除原文或“回译”并确认写回后，才会修改源文件。
• 保存原文只更新过期状态并刷新预览，不会自动请求翻译 API。
• 同步译文 只处理缺失块和过期块。
• 同步、重译和批量翻译按批次写入缓存；中途失败或取消时，已经成功写入的批次会保留，缺失块下次同步重试。
• 更换模型或需要刷新已有机器译文时，使用 全部重译；译文锁定块不会被覆盖。

译文锁定与预览内编辑

• 点击预览中的译文内容，会就地显示该块的原始 Markdown；点击 保存并锁定 后写入全局缓存，并标记为译文锁定。
• 也可以执行 编辑缓存 直接编辑缓存文件；修改并保存后同样会锁定该块。
• 点击原文内容可就地修改原始 Markdown；点击 暂存修改 后，预览会立即渲染暂存的原文结果，顶部会出现 应用原文修改。点击后会显示“当前原文 / 修改后原文”的分栏差异，确认后写回源 .md 并保存。
• 每个块有 插入 和 删除 按钮；点击后按钮展开为 原文 / 译文 两个选择，鼠标移出块后恢复：
  • 插入 → 原文：在该块后打开内联编辑器，点击 暂存新块 后立即出现在预览中；顶部 开头插入 可在文档开头插入。
  • 插入 → 译文：直接写入译文缓存的新译文块，立即进入导出，但不修改原文；可点击该块的 回译 生成原文候选，暂存后随原文修改一起写回并建立对应关系。
  • 删除 → 原文：把块标记为“原文待删除”，预览中变暗；可点击 撤销删除 恢复。应用写回后，该块已有的机器译文或锁定译文会降级为独立的译文锁定块（target 锚点），继续保留在导出中；原样复制块和已删除译文的标记会一并移除。
  • 删除 → 译文：在该块缓存中写入带备份的“已删除”标记，保留锚点；后续同步不会重译，导出的译文中也不包含该块内容；点击 撤销删除 直接恢复原译文或原复制/未翻译状态，不需要重新调用 AI。代码、公式等复制块和从未翻译的块同样可以删除。
  • 译文插入块可以直接删除，删除后从缓存中彻底移除，不提供撤销。
  • 所有暂存的原文修改、插入、删除都在同一份差异确认中写回，或点击 重置暂存 全部清除。
• 暂存修改按块记录；源文件在此期间被外部修改时，暂存会被清空并提示重新编辑。
• 原文再次变化时，译文锁定块进入“译文锁定 · 原文已更新”，不会被自动覆盖。
• 需要接受当前原文时，使用 标记已同步。
• 需要重译单个块时，使用该块上的 重新翻译。
• 每个已有译文的可翻译块都有 回译 按钮：把译文翻回原文语言，结果直接进入原文暂存，不弹出额外窗口；点击 应用原文修改 后写回源文件，并把这一个译文块锁定到新的原文。回译结果与当前原文一致时不会产生暂存修改。
• 稳定翻译 默认开启：重新翻译（单块/过期/全部）会把旧译文作为参考，回译会把当前原文作为参考；显式重译 human 块时也会参考旧译文。预览中的“参考上一版译文”开关只影响当前会话，设置页 stableTranslation 控制默认值。
• 全文摘要 只能手动生成（OpenAI 兼容/Mock），HTTP Provider 可手动填写。摘要面板显示状态、token 估算和过期提示；“AI 生成/保存/清除”会写回缓存。预览中的“使用全文摘要上下文”开关只影响当前会话，设置页 summaryContext 控制默认值。
• 摘要写入缓存内的专用标记，不参与块对齐和导出；源文变化后显示“可能过期”但仍会作为上下文使用；清除缓存时摘要一起删除。摘要生成输入上限约 12k tokens，超出时请手动填写。

块状态与缓存标记

缓存锚点（<!-- mbs:... -->）共有五种模式：

对齐后的块状态：untranslated、copy-pending、translated、stale、human、human-stale、copy、copy-stale、deleted。另外有三种暂存态：原文待插入、原文待删除、待生成的译文块。

分栏视图与滚动同步

• 预览顶部可在 并排 / 交错 / 分栏 三种布局间切换；布局会跨会话记住。
• 分栏 会创建原文、译文两个独立滚动窗格，而不是把每块的双语内容并排塞在一起。
• 滚动任一窗格时，另一侧会按块锚点同步到对应块；插入/删除造成的单侧块在缺失的一栏显示与并排/交错模式一致的普通块头和占位说明，两边仍保持一一对应的块行。
• 分栏中仍可执行原文/译文编辑、插入、删除、重译、回译与撤销删除；重新翻译 位于原文块，定位原文 位于译文块，插入和删除按钮在两栏都可用。
• 每个块标题栏右上角有 ⋯ 按钮，默认隐藏该块的全部操作；点击后操作按钮在标题下方换行展开，鼠标离开块时自动收起。仅原文/仅译文模式不显示 ⋯，操作按钮直接内联在块头右侧。
• 仅原文 / 仅译文 模式与分栏兼容，会保留对应窗格并占满宽度。
• 分栏的原文/译文标题右侧各有 只读预览 按钮。开启后该栏隐藏块级标题、状态和全部操作，连续渲染整栏 Markdown；另一栏可以继续编辑，也可以独立进入只读。切换只读或布局时会保留两栏滚动位置，不会跳回顶部。
• 只读状态按栏独立，只在当前预览会话内有效；关闭预览后恢复为可编辑。
• 只读模式仅影响显示与编辑入口，不改变同步、导出或缓存语义；单侧块在缺失的一栏不会生成占位块，只渲染实际存在的内容。

导入已有译文

• 可以在预览工具栏点击 导入译文，或从命令面板执行 导入已有译文…。
• 选择一份现有译文 .md，例如 guide.zh.md。
• 导入按顶层块逐一校验：原文与译文的块数量和块类型必须一致，避免段落错位。
• 所有可翻译块写入缓存并标记为 译文锁定；代码、公式等结构块按原文复制。
• 已有缓存会被覆盖，覆盖前会弹出确认；不提供缓存备份。
• 导入文件不能包含扩展锚点；如果你选择的是缓存文件，会提示改用无锚点的译文 Markdown。
• 导入不调用 AI，也不会修改源文件。

通用 HTTP Provider

• markdownBilingualSync.provider 设为 http 后启用。
• 请求方法支持 POST、PUT、PATCH；httpHeaders 与 httpBody 都是 JSON 模板。
• 模板变量：{{text}}、{{id}}、{{kind}}、{{headingPath}}、{{sourceLanguage}}、{{targetLanguage}}、{{apiKey}}、{{referenceText}}、{{referenceRole}}、{{summary}}。
• 通用 Provider 每个翻译块发送一次请求；httpResponseType 为 json 时按 httpResponsePath 提取文本，为 text 时直接把响应体作为译文。
• 稳定翻译参考和全文摘要只有模板显式引用 {{referenceText}}/{{summary}} 时才会发送；{{referenceRole}} 为 previous-target 或 previous-source。
• 示例 httpBody：

  {"text":"{{text}}","source_language":"{{sourceLanguage}}","target_language":"{{targetLanguage}}"}
  

• 示例 httpHeaders：

  {"Content-Type":"application/json","Authorization":"Bearer {{apiKey}}"}
  

• httpResponsePath 可设为 translation、data.translations.0.text 或 result[0].text。
• 接口地址除 localhost/127.0.0.1/[::1] 外必须使用 HTTPS；{{apiKey}} 只在请求时替换，不会写入设置或日志。

缓存清理

• 清理当前译文缓存 会删除当前文件的缓存，之后可重新翻译或重新导入；此操作不可撤销。
• 清除所有译文缓存 会递归删除扩展 globalStorageUri/cache 下的全部缓存文件，适合彻底重置；此操作不可撤销。
• 有缓存正在编辑器中打开时，清理命令会要求先关闭缓存标签页，避免编辑器继续持有已删除内容。
• 有同步或导入任务进行时，清除所有缓存会被拒绝，避免写入与删除交叉。
• 打开译文缓存目录 仍可直接查看所有缓存文件。

批量翻译与导出

• 批量翻译目录… 选择目录后递归查找 .md 文件，跳过当前目标语言的导出文件（如 *.zh.md），逐文件执行增量翻译。
• 批次按估算 token 预算动态打包，apiBatchSize 只是块数硬上限；会跨文件合并待翻译块，优先填满并发，同时避免低于预算约 25% 的过小批次。
• 文件级并发、同一文件内批次和手动同步请求共享 translationConcurrency 上限（默认 8，最大 100）。
• 每完成一个翻译批次就把成功结果写入缓存；某个文件后续批次失败时，已成功的块会保留，失败块留在未翻译状态，下次同步只补缺失部分。
• 批量翻译开始前会保存该目录下已打开的 Markdown 文件；进度通知可取消。单个文件失败不会中断其余文件，详情写入“输出”面板。
• 批量导出目录… 先扫描目录中已有缓存的 Markdown 并准备导出队列；内容未变化和无缓存的文件会跳过。
• 批量导出只显示一次汇总确认，不会逐个文件显示差异弹窗；确认后按队列写入语言后缀文件，并记录每个目标路径。

任务面板

• 状态栏右侧的 翻译任务 按钮在有任务时显示运行图标和 并发 x/y。
• 点击后切换右侧辅助侧边栏中的 翻译任务 WebviewView，不是编辑器标签页。
• VS Code 不允许扩展直接把视图放进辅助侧边栏。首次使用时，请把活动栏中的 翻译任务 图标/视图拖到右侧辅助侧边栏，之后 VS Code 会记住布局；状态栏按钮随后直接显示/隐藏该视图。
• 面板包含：
  • 批量总览：活动文件数、活动块进度、失败块、并发占用和等待请求。
  • 每文件明细：文件、阶段、块进度、失败数、耗时和错误。
  • 历史与错误：最近完成/失败任务，可清除历史。
  • 运行状态：翻译服务、模型/模板、批次预算和块数上限。
• 面板顶部可取消全部任务、清除历史、打开输出日志；每个文件可打开源文件或双语预览。
• 批量翻译和命令/预览触发的整文件同步不再弹 VS Code 进度通知或完成/失败通知，进度与结果统一进入该面板；取消确认、导入/导出确认和 API 配置提示仍保留。
• 任务行按文件级批量/同步统计；预览内单块重译、回译仍保留原有短操作反馈，不单独成行。
• 状态栏按钮不自动打开面板，按你的选择由按钮手动切换显示。

Provider 预设

• 执行 应用翻译服务预设…，可一键切换 OpenAI、DeepSeek、SiliconFlow、Ollama、LM Studio、自定义 HTTP 或 Mock。
• 预设只写入 provider、apiBaseUrl、apiModel 等接口设置，不写入 API Key。
• 本机服务预设使用 127.0.0.1 的 HTTP 地址；其余地址必须使用 HTTPS。
• 预设会覆盖当前接口与模型设置；API Key 仍需通过 设置 AI 翻译 API Key 单独保存。

导出

• 导出译文… 会生成同目录语言后缀文件，例如 docs/guide.zh.md。
• 导出前显示分栏差异；取消或写入后弹窗关闭，不保留独立 diff 标签页。
• 写入前会再次检查目标文件，确认期间被外部修改时拒绝覆盖。
• 导出去除内部锚点，是跨设备/跨项目的持久资产。

命令

设置

provider、接口、模型、HTTP 模板和批量设置是应用级设置，工作区不能覆盖。

安全与隐私

• API Key 只存入 VS Code SecretStorage，不写入设置、工作区、日志、提示词或缓存。通用 HTTP 模板中的 {{apiKey}} 只在发起请求时替换。
• OpenAI 兼容与通用 HTTP Provider 使用独立的 SecretStorage Key；旧版共用 Key 仅作为升级迁移回退。切换 Provider 或 endpoint 后请重新执行 测试 AI 翻译连接，确认 Key 与目标服务匹配。
• 原文写回（文档替换、保存、缓存对账）与同步任务共享同一文件锁；写回失败时会恢复内存文档，不会留下未保存的中间态。
• HTTP 模板中的未知变量、非法请求头、换行注入和远程明文 HTTP 会被拒绝；错误信息会遮盖密钥。
• 文档文本会发送到配置的翻译服务；请确认服务端的数据处理策略。
• 原始 HTML 不渲染；Webview 使用 CSP 和 nonce 限制脚本与资源。
• 译文缓存位于扩展的 globalStorageUri，不在项目目录中。
• 项目移动、清理扩展存储或卸载扩展会丢失缓存与锁定状态；需要长期保留的内容请导出。
• 术语表是用户级资源，不随仓库共享。

已知限制

• 仅支持本地文件流程；没有云端任务队列或多用户协作。
• 代码块、数学公式、HTML 和 frontmatter 按设计原样复制，不参与 AI 翻译。
• 预览内编辑按块进行，不支持跨块拖选或大范围结构重排；复杂结构调整建议直接编辑源文件。
• 分栏滚动同步按块对齐，不保证同一块内逐像素同步。
• 导入已有译文要求原文与译文顶层块数量和类型逐块一致；结构不同会拒绝导入。
• Provider 请求共享 translationConcurrency 并发上限（默认 8）；限流明显时调低，单文件块很多时可适当调高 apiBatchTokenBudget。
• 批量导出只提供一次汇总确认，不逐个文件显示差异预览；需要逐文件确认时使用普通导出。
• Provider 预设会覆盖当前接口与模型设置，但不会写入或清除 API Key。
• 通用 HTTP Provider 每个块发送一次请求，不支持批量 items 协议；需要批量的服务可先使用 OpenAI 兼容适配层。
• 插入/删除的“原文”操作修改源文件；“删除译文”在缓存中写入删除标记并保留锚点，不删除源块；无原文的译文插入块删除后直接从缓存移除，不可撤销。
• 译文插入块直接写入缓存，不修改原文；如果其锚定的原文块被删除，译文块会按前一个仍然存在的原文块或目标末尾排序。
• 删除原文块并写回后，对应译文会自动降级为独立译文块（target 锚点），不会产生孤立锚点或阻止后续同步。
• 清理当前缓存或清除所有缓存后无法在扩展内恢复；需要长期保留的译文请先导出。
• 回译按块执行，不会自动批量回译整个文档。
• 全文摘要只能手动生成；HTTP Provider 不支持自动生成摘要，只能手动填写；超大文档（超过约 12k tokens）目前不自动分段摘要。
• 摘要和稳定参考会增加每次翻译的输入 token；摘要上下文按每批固定开销计入预算。
• 不支持 Mermaid、原始 HTML、自定义提示词和流式输出。
• 术语表是全局的，不支持项目级覆盖。
• UI 目前仅提供中文；界面、预览和通知文案集中在 src/i18n/zh.ts，领域诊断文案仍随模块内联。
• 非实时同步：保存只标记状态，翻译由手动命令触发。

许可证

本项目采用 MIT License（见仓库根目录的 LICENSE 文件）。你可以自由使用、修改和分发，但需保留版权与许可声明。

开发

npm install
npm run typecheck
npm test
npm run compile
npm run preview:sample
npm run package

打包产物位于 artifacts/vsix/markdown-bilingual-sync.vsix。示例文档为 samples/demo.md。

CI 配置位于 .github/workflows/ci.yml：每次推送和拉取请求会执行 npm ci、类型检查、全量测试，并打包 VSIX 作为构建产物。

路线图

Phase 2 — 维护能力（已完成）

• 导入已有译文并全量标记为译文锁定。
• 真正的左右分栏与块级滚动同步。
• 通用 HTTP Provider 模板（Key 仍只存 SecretStorage）。
• 缓存打开/清理脚手架。

Phase 3 — 效率与发布准备（已完成）

• 目录/批量翻译与导出队列。
• Provider 预设与缓存清理（缓存路径按源文件哈希确定性生成，不需要额外索引）。
• CI/集成测试与发布准备（当前 UI 仅中文）。