如何翻译 Markdown 文件？-1 - 难点及解决方案

背景

近期在搭建英文博客 -<e-whisper.com>, 需要对现有的所有中文 Markdown 翻译为英文.

需求如下:

• 将 Markdown 文件从中文 (zh-CN) 翻译为英文 (en)
• 翻译后要保留 Markdown 的完整格式
• 部分 Markdown block 不需要翻译，如: front-matter、代码块 等

但是实际使用中，试了好几款翻译（包括 Google，DeepL，Azure）, 结果发现效果都不理想.

为什么要翻译 Markdown 文件

为什么要翻译 Markdown 文件？翻译 HTML 文件不行吗？

这是因为现在越来越多的工具使用 Markdown 来组织他们的内容。比如：

• Gitbook，Obsidian 作为文档、笔记的工具
• Hexo（我用的就是 Hexo），Jekyll，Hugo 作为静态网站生成器（SSG）
• Strapi 等作为内容管理系统（CMS）

根据项目的情况，或是目标受众的情况，有必要生成多语言内容并定期更新。

Markdown 翻译的难点

我试了好几款翻译工具来翻译 Markdown，但翻译结果并不理想。遇到的常见问题有：

• Markdown 语法被损坏
  • 如：test 后一个标点被翻译为单引号
• 翻译一些不应该被翻译的内容，如:
  • Front-matter
  • 代码段
  • :: 格式的代码段等
• 翻译结果中出现了不同的 Markdown flavor
• 需要复杂的设置

这里有几个典型的翻译后的例子，如下:

``Shell
echo "Hello world!"
```

代码段损坏了，因为被围起来的代码块现在是以两个背号而不是三个背号开始。另外，语言 Shell 的名称现在是大写的。

还有一个例子翻译后更糟糕，如下:

原文:

You can search for files in `./blog/posts/en/*.md` and translate them to `./blog/posts/$locale/$FILE.md`.

## :smile:

翻译后:

你可以搜索 "./blog/posts/en / *. Md"  中的文件，并将其翻译成 ". / Blog / posts / $ locale / $ FILE.md"。

## : smile:

Path 被分割开来，并有不同的标记。表情符号也被破坏了。

还有一个例子，如下:

原文:

```YAML
- name: Unlock sudo
lineinfile:
    dest: /etc/sudoers
    regexp: '{{ ansible_env.USER }} ALL=\(ALL\) NOPASSWD: ALL'
    line: '{{ ansible_env.USER }} ALL=(ALL) NOPASSWD: ALL'
    validate: visudo -cf %s
become: yes
```

翻译后:

```YAML
- 名称：解锁sudo
lineinfile：
    dest：/ etc / sudoers
    正则表达式：'{{ansible_env.USER}} ALL = \（ALL \）NOPASSWD：ALL'
    行：“{{ansible_env.USER}} ALL =（ALL）NOPASSWD：ALL'
    验证：visudo -cf％s
成为：是的
```

翻译了不应该被翻译的代码块.

Markdown 解决方案

针对 Markdown 语法特点，大致有 2 种解决方案:

• 转换为 HTML 再翻译
• 将 Markdown 根据其语法格式拆分为 "段", 分别对这些 "段" 进行处理

Markdown 转 HTML -> 翻译 -> 再转回 Markdown

1. 将 Markdown 转换为 HTML。
2. 将其作为 HTML 发送到翻译的 API。(如 Google/Azure/DeppL 的 API)
3. 将收到的 HTML 转换为 Markdown。(如 pandoc)

这样代码块不再被谷歌翻译毁掉了！
然而，这样操作，还会引入一些新的问题。

1. 在翻译成 HTML 时，包括换行在内的连续空白被转换为一个空格。该代码块也不例外。
2. 同样，在 <code> 和 <pre> 之间也插入了一个空格，这使得人们无法识别它是代码块的一个栅栏。

这些问题也容易解决。
只需使用正则表达式替换换行和缩进。例如，<br> 和  。

但是这种解决方案，还是存在一些硬伤的，典型的就是上面提到的空格的问题.
另外就是针对多级有序 / 无需列表，多级缩进的情况下，来回转换容易导致格式错乱，更严重的甚至导致部分内容的丢失.

将 Markdown 拆分为 "段"

1. 将文件分解成 "段"。
2. 获得一对句子和一个块的信息。例如，该块是一个标题、一个段落、一个代码块还是其他。
3. 如果该 "段" 不是代码块或 Frontmatter，则将该文本发送到翻译的 API。
4. 用收到的句子覆盖该块中的句子。
5. 以 Markdown 格式再次构建。
6. 保存为新的文件名。

这种情况下，可以根据 Markdown 的语法进行定制化，甚至根据自己不同的 Markdown flavor 和语法扩展对其定制。但是由此带来的就是工作量比较大.

另外这种解决方案，还存在的一个潜在问题就是由于将整篇 Markdown 拆分为大量的小 "段":

1. 可能无法利用当前翻译 API 的上下文语义理解功能。同一个单词可能会被翻译为不同的结果。单只翻译质量不佳.
2. 调用 API 的次数变多，导致费用的上升.

总结

刚开始，我是计划发布一个英文博客站点 - <e-whisper.com>, 由此计划将 Hexo 下的中文 markdown posts 都翻译为英文.

但是在翻译的过程中，却面临一系列的困难，如:

• Markdown 语法被损坏
• 翻译一些不应该被翻译的内容，如:
• 翻译结果中出现了不同的 Markdown flavor

并以此提出翻译 Markdown 常见的 2 种方案:

• 转换为 HTML, 再翻译
• 将 Markdown 分隔为 "段", 以 "段" 为单位进行翻译

并分析了 2 种方案的优劣.

但不论如何，翻译后还是需要人去 review, 修正。另外在翻译专业技术类文章时，如果某个翻译 API 支持 "单词库" 功能真的是太刚需了.

希望对各位有所帮助.