Markdown (.md) 文件怎么翻译且不乱代码块与链接
意扣 Equalang导读
用 Pandoc 将 Markdown (.md) 转为 HTML 再经意扣翻译并转回,或在浏览器直接双语对照阅读 GitHub 文档,保护代码块、链接和表格不走样。
关键词:translate markdown file; Markdown文件翻译; md文件怎么翻译; 翻译md文件保留代码块; GitHub README翻译
把 .md(Markdown)源码直接复制进普通网页翻译框,或者把后缀强行改成 .txt 上传,十有八九会把排版毁掉:[文字](链接) 中间被塞进空格导致超链接失效,三重反引号代码块里的命令行参数和变量名被翻成中文,| 表格竖线错位,甚至静态博客头部的 YAML 配置键名(如 title:、slug:)也被一起翻译,导致构建直接报错。如果你需要拿到一份格式完好的译文 .md 文件提交回代码仓库,最稳妥的做法是先用 Pandoc 把 .md 转成 .html,交给识别 HTML 代码标签的文档翻译工具处理,翻完再转回 Markdown;如果只是想读懂 GitHub 或文档站上的外文 README.md,不用折腾文件转换,直接在浏览器里对渲染后的网页开双语对照就行。
为什么直接翻译 Markdown 源码总出问题?
按照 CommonMark 规范,Markdown 的设计初衷就是把正文和排版符号混写在同一层纯文本里:# 代表标题、[锚文本](url) 代表链接、单反引号包裹行内代码、三重反引号(```)包裹代码块、| 竖线拼出表格。使用 Hugo、Astro 或 Docusaurus 搭建的文档站,还会在文件开头用 --- 包围一段 YAML front matter 元数据。
当纯文本翻译接口读到这些符号时,它看到的不是文档结构树,而是普通标点符号,最常踩的坑有四个:
- 链接与图片路径断裂:翻译引擎习惯在括号前后补空格或换全角括号,把
[安装指南](./docs/install.md)变成[安装指南] (./docs/install.md),甚至把相对路径里的文件名也翻译掉。 - 代码块与命令参数被误翻:
```bash等语言标记被拆散,代码里的--dry-run、环境变量名和注释被翻成半中半英,读者复制出来根本跑不通。 - 表格竖线坍塌:译文长度变化或全角符号混入后,用来分列的
|符号数量对不上,渲染出来直接退化成一团乱码。 - YAML 元数据报错:一旦 front matter 里的
layout: doc或draft: false被翻译,静态站点生成器编译时就会立刻抛错中断。
方案一:用 HTML 中转翻译并转回 .md(适合需要交付 .md 文件)
先坦诚说明格式边界:意扣(Equalang)的文档翻译支持 HTML、PDF、DOCX、PPTX、XLSX、EPUB 和 TXT,目前不直接接收 .md 后缀的文件。千万不要为了上传而把 README.md 改名成 README.txt——一旦按 .txt 纯文本处理,所有 Markdown 语法符号都会暴露在正文翻译里。
可靠的做法是用 .html 做一次中转。把 Markdown 编译成 HTML 后,代码块会被装进标准的 <pre><code>...</code></pre> 标签,行内代码会放进 <code> 标签,链接地址则会收进 <a href="..."> 属性里。这样意扣在翻译 HTML 时,只会翻译标签之间的自然语言正文,而把代码块内容和链接指向原封不动地留住。

第一步:用 Pandoc 将 .md 转为 .html
Pandoc 是支持 macOS、Linux 和 Windows 的开源文档转换工具。在终端进入 .md 文件所在目录,运行:
pandoc README.md -f gfm -t html -o README.html
参数 -f gfm 表示按 GitHub Flavored Markdown 语法解析,能把表格、任务列表和带语言标记的代码块准确转换成 <table>、<pre><code> 等 HTML 节点。
关于 YAML front matter 的处理提示:默认不加 -s(独立完整文档)转换时,Pandoc 会自动剥离文件开头的 --- YAML 元数据块,刚好避免配置项被送去翻译。如果你的文档是 Hugo 或 Docusaurus 博客,建议先把原文件头部的 --- 块复制留存,等第三步生成译文 .md 后再贴回文件最上方,只手动改一下其中的 title 和 description 字符串即可。
第二步:上传 .html 翻译并在工作台左右核对
打开意扣的文档翻译页面,上传刚刚生成的 README.html 并选择目标语言。文档翻译目前支持中文、英文、日语、韩语、西班牙语、法语等多种语言,源语言支持自动识别。网页端每次上传一个文件,可以一个接一个连续上传、不限总个数(同一账号同时最多处理 3 份文档,其余任务自动排队)。
翻译完成后,先在网站的翻译工作台(Translation workspace)里点开查看:左边原文、右边译文并排显示,支持两栏同步滚动。下载 README.translated.html 之前,重点扫一眼两件事:
- 多行代码块里的命令、参数和代码缩进是否保持原样。
- 夹在句子中间的
<code>函数名、配置项名称是否完好地嵌在译文句子里。
第三步:用 Pandoc 把译后 HTML 转回 Markdown
拿到翻译好的 HTML 文件后,再用 Pandoc 反向转回 GitHub 风格的 Markdown:
pandoc README.translated.html -f html -t gfm --wrap=none -o README.zh.md
这里一定要加上 --wrap=none。Pandoc 默认会在第 72 个字符处强制折行,加上 --wrap=none 能让每个自然段保持单行,不仅方便做 git diff 对比,也能避免长表格或列表项因为硬换行而变形。最后,如果原文件带有 YAML front matter,把它贴回 README.zh.md 顶部即可。
方案二:只看不改?直接在浏览器里双语对照读 GitHub 文档
如果你并不是要给开源项目提交多语言 .md 源码,只是在逛 GitHub、GitLab 或海外技术文档站时想顺畅读完一篇长 README.md,那就完全没必要下载文件再跑命令行。
当你在桌面浏览器里打开 GitHub 上的 .md 页面时,平台已经把 Markdown 渲染成了标准网页。这时直接用意扣浏览器插件(支持 Chrome、Edge、Firefox,Mac 上的 Safari 18.4 及以上版本也提供临时安装包)开启网页双语阅读即可:
- 在浏览器中打开 GitHub 仓库的
README.md或任意在线文档页。 - 点开插件面板,选好目标语言并开启「双语对照」。
- 往下滚动阅读时,每段译文会直接出现在对应原文段落的下方;页面上的代码块和指向仓库其他文件的超链接都留在原位。再按一次即可切回纯原文。
如果整篇文档你大部分都能看懂,只是偶尔卡在几个长句或专业术语上,可以不开整页翻译,只在插件面板里打开「划词翻译」:鼠标选中那句英文,点击旁边浮出的翻译图标,就能在浮窗里看当前语境下的译法。想了解更详细的网页对照操作,可以读这篇外文网站双语对照阅读指南。
浏览器插件和网站文档翻译共用同一个账号与积分余额,不需要分开充值。具体计费规则可以查看价格页——新账号注册即送 200 积分,足够你拿手头的文档或网页先试跑一遍。
提交代码前要留意的三个边界
即便走 HTML 中转保住了代码块和超链接,Markdown 生态里仍有三处细节需要你在提交 PR 前人工扫一眼:
- 页内标题锚点(
#section-name):GitHub 和多数静态站点会根据标题文字自动生成跳转锚点。当## Quick Start被译成## 快速开始后,标题对应的锚点 ID 也会跟着变,文件开头目录里的[快速开始](#quick-start)就可能跳不过去,需要把括号里的#quick-start一并改成新标题对应的锚点。 - MDX 与自定义短代码(Shortcodes):如果文档是
.mdx(混有<Callout>等 React 组件)或带有 Hugo 的{{< note >}}短代码,Pandoc 在转 HTML 时可能会把自定义标签转义或吞掉。这类文件建议先拿单篇测试并对比git diff,确认组件标签没丢再批量处理。 - 被误标成行内代码的普通词:因为 HTML 翻译会保护
<code>标签里的内容不翻译,如果原作者习惯用单反引号来高亮普通英文名词(而不是真正的代码标识符),这些词在译文里也会保留英文原样,核对时按需改成目标语言即可。
常见问题
意扣可以直接上传 .md 文件,或者把 .md 改名为 .txt 上传吗?
不可以。意扣文档翻译目前支持 HTML、PDF、DOCX、PPTX、XLSX、EPUB 和 TXT,不直接接收 .md。请不要把 .md 后缀改成 .txt 上传,因为 .txt 会按纯文本处理,不会解析 Markdown 语法,代码块、链接括号和表格竖线都会被当成普通句子拆分翻译。请先用 Pandoc 转为 .html 再上传。
怎么把 Markdown 文件翻译成英文或中文且不破坏代码块?
先在终端运行 pandoc input.md -f gfm -t html -o input.html 把 Markdown 转为 HTML,使代码块被 <pre><code> 标签包裹;接着把 input.html 上传到意扣文档翻译;下载译文 HTML 后,再运行 pandoc output.html -f html -t gfm --wrap=none -o output.md 转回 Markdown。
在 GitHub 上看英文 README.md,怎么最快双语对照阅读?
无需下载 .md 源文件,直接在 Chrome、Edge 或 Firefox 中打开该 GitHub 页面,启用意扣浏览器插件的网页双语对照功能。随着页面向下滚动,每段英文下方会直接显示中文译文,而页面上的代码块与仓库链接保持原状。