多語系 Sphinx 與 Python 官方文件中文化

Liang-Bo Wang (亮亮), 2016-06-03

多語系 Sphinx 與
Python 官方文件中文化

By Liang2 under CC 4.0 BY license

Esc to overview
to navigate

多語系 Sphinx

Sphinx 文件產生工具

製作一個 Sphinx 文件

demo_sphinx
├── _build/
├── Makefile
├── make.bat
├── conf.py
├── index.rst
├── intro.rst
└── api.rst
				Welcome to Demo project for sphinx-intl's documentation!
========================================================

We will use this to demo the usage of `sphinx-intl`_.
Make sure you make installed all the required packages:

.. code-block:: bash

    pip install -r requirements.txt

Then try to write some more pages.

Contents:

.. toctree::
   :maxdepth: 2

   intro
   api
			

index.rst

				Intro
=====

Sphinx
------

**Sphinx** is an excellent Python documentation generator. From |Wikipedia|_,

    Sphinx is a documentation generator, heavily used (and written) by the
    Python community. It's also written in Python (a programming language); but
    used by many other environments.

.. |Wikipedia| replace:: *Wikipedia*
.. _Wikipedia: https://en.wikipedia.org/wiki/Sphinx_%28documentation_generator%29

It use reStructuredText (rst) for as the markup language for documents. An
rst document usually looks like:
			

intro.rst

				GNU ``gettext`` API
===================

Extract some docstring of :mod:`gettext` here (see the `full module description`_).

.. function:: gettext(message)

   Return the localized translation of *message*, based on the current global
   domain, language, and locale directory.  This function is usually aliased as
   :func:`_` in the local namespace (see examples below).

.. _full module description: https://docs.python.org/3.5/library/gettext.html

Here's an example of typical usage for this API:

.. code-block:: python3

   import gettext
   gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
   # ...

			

api.rst

多語系 (i18n)

Sphinx 多語系 (i18n)

建立翻譯對照檔:gettext

Ref: Typical gettext workflow on Wikipedia
by Quicksilver (CC BY-SA 3.0)

po 檔長怎樣

#: ../../index.rst:15
msgid "Then try to write some more pages."
msgstr "接著試著撰寫一些頁面。"

#: ../../index.rst:17
msgid "Contents:"
msgstr "內容:"

Sphinx 多語系 123

  1. make gettext 建立 .pot 翻譯模版
  2. sphinx-intl update -l zh_Hant
    生成或更新已經建立每個 .rst 文件對應的 zh_Hant .po 檔
    (產生 index.po、intro.po、api.po)
  3. 翻譯,修改 zh_Hant .po 檔
  4. make -e SPHINXOPTS="-D language='zh_Hant'" html
    生成 zh_Hant HTML 文件

\ 就這麼簡單 /

流程示意圖:

Ref: Workflow visualization of translations in Sphinx, Sphinx Internationalization

林林總總

demo_sphinx/
├── _build/
│   ├── doctrees/
│   └── html/
├── Makefile
├── make.bat
├── conf.py
├── *.rst
└── locale/
    ├── pot/
    │   └── *.pot
    └── zh_Hant/
        └── LC_MESSAGES/
            ├── *.mo
            └── *.po

git checkout e294445 切換不同 commit

Python
官方文件中文化

https://docs.python.org.tw/3/index.html

「原文」連結連回官方英文版同標題處

Python 官方文件中文化

加入中文化翻譯 123

  1. 註冊 Transifex 帳號,加入 python-35-tw 翻譯專案
  2. 選擇想要翻譯的頁面,例如 https://docs.python.org.tw/3/tutorial/introduction.html 即為 tutorial--controlflow
  3. 開始翻譯,參考翻譯守則的規定,注意 rst 語法
  4. 點擊翻譯頁面側邊欄的 "Update Translation" 連結
  5. 看一下 doc page build 排程 是否順利結束
  6. 重整翻譯頁面確認結果

點擊 "Update Translation" 連結,查看 doc page build 排程

工作完成後,可以看排程實際執行了哪些指令,或 build doc 有沒有錯誤。

檢查翻譯成果

僅參與翻譯的話,一行指令都不用下

對想要離線使用的人,參考 wiki 說明(跟前半場 talk 操作類似),新的翻譯每天都會自動加回 git repo 中。

自動更新 Sphinx 文件排程實作

盡量讓環境的建立都有文件,可以推坑傳承。避免一年後的自己都搞不懂

待改善之處

翻譯現狀與挑戰

翻譯現狀

Modified from リトルウィッチアカデミア (Little Witch Academia), 2013

翻譯挑戰

翻譯文件此坑有多大?

類型 翻譯條目數 字數 內容
tutorial/* 0.8k 25k 給初學者的教學
installing/*, using/* 0.8k 15k 在各系統上安裝與使用
howto/* 2k 60k 針對套件的詳細教學
reference/* 13k 38k Python 語言定義
library/* 25k 513k 標準函式庫 (stdlib)
TOTAL 42k 661k

(word count using pocount from translation-toolkit)

Ref: Amazon

魔戒三部曲 + 前傳 (= 560k)

Ref リトルウィッチアカデミア 魔法仕掛けのパレード (Little Witch Academia: The Enchanted Parade), 2015

翻譯時程

本來是要帥氣地在 PyCon TW 宣布 tutorial 完成翻譯的,
但申請學校 + 畢業 + PyCon TW 議程長負擔真的有點多……

贊助?

Tutorial 以外的內容,除了參與翻譯外,也歡迎各位贊助

如果贊助成真,收集到的資金將由第三方統籌並公開收支(PyCon TW?)

總結

歡迎加入專案或來信至 [email protected]
PGP fingerprint 6ECD C5B8 235C D44D 2471 866E 30A4 5011 B233 544E

Ref リトルウィッチアカデミア 魔法仕掛けのパレード (Little Witch Academia: The Enchanted Parade), 2015

My goodbye gift before leaving Taiwan :)

About Me

(Yap, I know I haven't changed my protrait photo since 2014)

?

Sources on GitHub