使用Sphinx翻译odoo的文档-变英文为中文

Sphinx是一款非常方便的文档生成工具，Odoo文档亦是使用其生成。

整个文档部分整理的非常整洁。下载的最新版odoo的源码，doc目录已经完全可使用Sphinx生成文档，于是我也学习了一些Sphinx的相关用法。

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

pip install sphinx --upgrade
pip install sphinx-intl

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

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

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

基本HTML文档的构建

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

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

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

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

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

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

   language = 'zh_CN' # language supported 
   locale_dirs = ['locale/'] # path is example but recommended. 
   gettext_compact = False # optional.

2. 抽取需要转换的文本到pot文件列表中
   执行如下指令即可：

   $ make gettext

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

3. 更新对应语言的版本

   $ sphinx-intl update -p _build/locale -l zh_CN

4. 手动翻译抽取后的文段
   这时，我们将可以在locale目录，注意，是文档项目根目录下的locale，这才是我们要翻译文本的.po文件夹。里面内容大概如下：

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

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

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

看下效果

研究sphinx+晚上翻译，将Odoo官网首页翻译了个大概，有兴趣的朋友可以看下我发布的中文文档：

http://www.odooapp.cn

发布项目的小问题

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

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