Sphinx翻译Flask-PyMongo小记

2019-01-02 Code Fancy

restructuredText语法编写Sphinx翻译

#环境准备

可能你和我一样早就注意到，许多Python的文档甚至是翻译文档无论是风格还是结构都十分相似，赏心悦目条理清楚的文档让阅读变得舒心。而其中大部分都是通过Sphinx撰写的，我之前的所有知识，哪怕学到学到一点

Sphinx是一个Python编写的一个非常好用的撰写文档框架，http://www.sphinx-doc.org/en/stable/# 主要使用reStructuredText语法来提供文档控制，也支持Markdown等的文档标记语言。restructuredText语法相较严格正规，好用的Directive Latex集成注释等等使得完全可以满足提供正规出版文档的需求。这次翻译文档之前需要先熟悉restructuredText语法，语法相较简单，编写文档的话还是要慢慢熟悉。

项目引入

我们先fork一份要翻译的文档项目，比如我们这回的flask-pymongo为例，因为是初次翻译，避重就轻了一点，其实最好还是和作者联系一下。

github

拷贝到本地后仅保留docs文件夹即可。然后在github里新建一个仓库。作者这里之前用的pip，我们使用pipenv创建环境后需要手动安装reqirements.txt的依赖。这是非必须的，作者在这里借助包同步版本号，我们更新并没有那么及时，可以手动更改本地化的版本。

部署完pipenv环境后首先安装Sphinx，以Ubuntu环境为例

  $ pipenv install sphinx 
  $ pipenv install sphinix-intl

这里的sphinix-intl是本地化翻译用的命令行工具，可以方便我们抽取.po文件Sphinx的操作基本还是依赖命令行。

另外，可能你在StackOverFlow已经遇到过一个奇葩的缩写了，真的这里带了三个概念

国际化 (Internationalzation) 因为I与N之间有18个字母所以缩写为I18n
本地化 (Localization) 因为L与N之间有10个字母所以缩写为L10n
全球化 (Globalization) 同时进行了国际化与本地话，缩写G11n

.po文件是GNU下gettext的一套应用规范，类似于Babel等诸多L10n工作都会用得到

这里我们配置下conf.py这里储存了Sphinx的配置，我们添加一个中文支持 vi conf.py:

  # The language for content autogenerated by Sphinx. Refer to documentation      
  # for a list of supported languages.                                            
  language = 'zh_CN'        #语言支持
  locale_dirs = ['locale/'] # 目录必须要定义，这里仅是示例
  gettext_compact = False #可选项，提供gettext兼容

翻译

整个翻译过程有四个步骤：

我们这里提取标记文本，生成POT文件，拓展名即为.pot(Portable Object Template)即可移植对象模板

$ make gettext

如果前方配置正确的话，sphinx可能会这样显示

sphinx-build -b gettext . _build/locale Running Sphinx v1.8.2 loading translations [zh_CN]… done making output directory… … Build finished. The message catalogs are in _build/locale.

_build目录下出现我们定义的locale文件夹，里面对应生成的.pot即是我们要翻译的文档，我这里是index.pot

更新对应语言，提取文件到po列表

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

Sphinx可能会这样显示

  >Create: locale/zh_CN/LC_MESSAGES/index.po

据Sphinx提示，本地生成了locale文件夹，里面的LC_MESSAGES中的index.po即是我们的po文件，要翻译的片段由三部分组成

  #: ../../index.rst:12 #片段所在文件与代码行数
  msgid "提取出待翻译的源片段"
  msgstr "你要翻译的汉语位置"

用VIM的PO插件po.vim,或者是Poedit 这世界上翻译有两种，Google翻译和其他翻译，Poedit免费版提供的就是没什么卵用的其他翻译。 poedit

编辑需特别注意rst文件格式语法存在的大量半角空格，编辑后我们make即可生成对应的编译MO文件和PO在同一目录，可以make html生成html查看效果。如果出现这种情况， Error 系语法错误，对照生成在_build/html里的对应html文件修改 fininshed

至此，编译完成，我们先将编译好的文档上传到github。然后选择文档托管平台，这里以Read the Docs为例。

##推送至Read the Docs

我们需要进入到 ReadtheDocs官网注册个账号，注册后如果个人界面，点Import a Respository导入Github项目

命名好名字，进入设置里，Setting里下拖Language选择Simplfied Chinese或者其他翻译的语言 setting

Advanced Settings更改好本地化语言与Python3 环境，可以去掉Enable PDF build:的勾以防止 change 点Build version

import

完成，等网站地图更新后，我们就可以在搜索里找到自己翻译的文档了

over

#后记

其实真的不知道如何才能报答开源社区，到目前为止我的所有知识都是社区所教，如果我学得了一丝一毫的能力，得到了哪怕一点点成就，那都得感谢社区里的大家。