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

#後記

其實真的不知道如何才能報答開源社區，到目前為止我的所有知識都是社區所教，如果我學得了一絲一毫的能力，得到了哪怕一點點成就，那都得感謝社區裏的大家。