使用Sphinx翻译LLVM的中文文档

Sphinx是一款非常方便的文档生成工具,以前就早有耳闻,最近计划将LLVM的文档翻译一些,在打开LLVM的文档源文件后发现,整个文档部分整理的非常整洁。下载的最新版LLVM-3.8版的源码,已经完全使用Sphinx生成文档,于是我也学习了一些Sphinx的相关用法。

Sphinx是python编写的一款命令行工具,在python3或python2下都能正常的工作,安装可以使用流行的pip进行安装:

1
2
$ pip install sphinx --upgrade
$ pip install sphinx-intl

Sphinx的依赖项比较新,最好还是更新一下比较好。sphinx-intl是一个命令行工具,用来实现多语言翻译的。

Sphinx有着非常独特且方便的代码翻译模型,可以用工具将英语版编写的文档中的文字全部抽取出来,在.po文件下,可以让用户方便地进行修改和翻译。最后根据生成时的语言配置,构建对应语言版本的文档。

sphinx i18n model

不过我们先不管Sphinx是如何进行翻译抽取的,先来看下LLVM文档的构建。

基本HTML文档的构建

默认LLVM的docs目录下的makefile是给doxygen使用的,这里我将Makefile.sphinx改成默认的makefile。这样接下来的命令中,都不会再出现对于原版-f Makefile.sphinx参数了。

首先对于构建html版本,非常简单,直接make默认参数即可,或者make html都可以。

这样,会在_build目录下生成对应的网站文件夹。

这样构建的文档,是可以作为静态网站直接发布出去的,不过发布到github上的gitpages上还是会有点问题,我们这里先不谈,接下来的发布注意中再细说。

抽取文档中的文本并开始翻译

我们的目标是翻译,将英文文档尽可能正确无误地转换为中文文档。这里我们使用sphinx-intl工具进行翻译。

  1. 首先配置conf.py文件
    conf.py是sphinx的配置文件,我们需要为其增加国际化翻译文件夹:

    1
    2
    3
    language = 'zh_CN' # language supported
    locale_dirs = ['locale/'] # path is example but recommended.
    gettext_compact = False # optional.
  2. 抽取需要转换的文本到pot文件列表中
    执行如下指令即可:

    1
    $ make gettext

    这时,会在_build目录出现一个locale文件夹,是抽取出的全部文本段。

  3. 更新对应语言的版本

    1
    $ sphinx-intl update -p _build/locale -l zh_CN
  4. 手动翻译抽取后的文段
    这时,我们将可以在locale目录,注意,是文档项目根目录下的locale,这才是我们要翻译文本的.po文件夹。里面内容大概如下:

    1
    2
    3
    #: ../../builders.rst:4
    msgid "Available builders"
    msgstr "<一些你要翻译的汉语>"

    msgid和msgstr一对一句,是全部抽取出来的文本的翻译,只要你对应翻译,注意rst文件的格式,翻译出来很少会出问题,样式完全一致,而且链接不会错乱。

  5. 构建新版文档
    由于我们在conf.py下配置了默认的language,所以只要这时再重新make,项目文档就生成成中文版的了。

看下效果

今天一下午研究sphinx+晚上翻译,将LLVM官网首页翻译了个大概,有兴趣的朋友可以看下我发布到gitpages上的中文文档:

http://sunxfancy.github.io/llvm-cn/

另外英语好且正在使用LLVM的朋友,欢迎一同和我来翻译这个项目,给更多人带来便利。

发布项目的小问题

之前我们提到,发布到gitpages出些问题,所有_static等带_前缀的文件夹无法访问,思考了一下,觉得是github本身的问题,在看sphinx文档的时候,发现提到了一个文件,必须同时发布到gitpages上。

.nojekyll,这个空的小文件十分重要,因为它直接关系着github上的解析规则,加上这个空文件,gitpages就会停止默认的过滤规则,运行我们的资源文件的访问。