緣起

Python 是方便強大的動態語言，在西方世界有許多的使用者。然而，在台灣一直沒有突破性的發展。身處軟體工業並不發達的國家，Python 無法在台灣流行有許多原因，但缺乏適當的中文文件，確是理由之一。

為此，PyTUG 決定開始 Python 文件的繁體中譯計畫，將最新的 Python 官方文件譯為符合本地用語的繁體中文版。本中譯計畫暫定名為 pydoccht。

目標

完整翻譯 Python official documentation 至繁體中文，並持續自上游更新。

信條

必求正確，力求精準。

成果授權

因 pydoccht 為文件翻譯計畫，故完全遵照原始文件之授權。

技術需求

pydoccht 的進行需要一些技術基礎，茲列出如下。

1. docutils/rst and sphinx

   新版 Python official document (以下稱 pydoc) 在 Python 2.6 trunk 中已捨 LaTeX 改採 reStructuredText。事實上，這是 yungyuc 決定發起 pydoccht 計畫的主因；相較於 LaTeX，reStructuredText 對中文非常友善，pydoc 所使用的文件工具將可能可以直接套用在 pydoccht 上。

   sphinx 是新版 pydoc 所使用的文件產生框架。

2. make

   pydoc 使用 make 作為 build tool，故需熟悉 Makefile 與 make。

3. mercurial

   pydoccht 用 mercurial 為 VCS，canonical repository 為 http://hg.seety.org/translating/pydoccht/。透過 mercurial，pydoccht 以去中心化的方式進行多方合作。

4. roundup

   mat 用 roundup 為本計畫建了一個 issue tracker，位於 http://project.python.org.tw/pydoccht/。我們將會使用這套系統分派工作，並且以之為主要討論的平台。

5. subversion

   Python trunk 使用 subversion，故為了自 trunk checkout 最新的 pydoc 與相關工具，我們也要使用 subversion。

pydoc 簡述

pydoc 是本計畫的上游，翻譯的目標。主要分為數部文件：

• What's New：「更新說明」，位於 whatsnew 目錄。
• Tutorial：「Python 入門手冊」，位於 tutorial 目錄。
• Using Python：「使用 Python」，位於 using 目錄。
• Language Reference：「Python 語言參考手冊」，位於 reference 目錄。
• Library Reference：「Python 程式庫參考手冊」，位於 library 目錄。
• Python HOWTOs：「Python HOWTOs」，位於 howto 目錄。
• Extending and Embedding：「延伸與嵌入 Python 直譯器」，位於 extending 目錄。
• Python/C API：「Python/C API 參考手冊」，位於 c-api 目錄。
• Installing Python Modules：「安裝 Python 模組」，位於 installing 目錄。
• Distributing Python Modules：「散佈 Python 模組」，位於 distutils 目錄。
• Documenting Python：「Python 文件」，位於 documenting 目錄。

團隊合作

pydoccht (本中譯計畫) 將會以 http://project.python.org.tw/pydoccht/ 作為討論平台，並以 http://groups.google.com/group/pythontw 作為正式的消息發佈管道；所有參與者均應注意其中的訊息。同時鼓勵團隊成員使用 #python.tw/Freenode 頻道即時討論。

pydoccht 計畫的分工為：

• 協調員 (coordinator)：最初的 coordinator 為計畫的發起人 yungyuc，目前仍為 yungyuc。

• 譯者 (translator)：負責翻譯，以章為單位。因 pydoc 基本上一章一檔，故每位譯者負責一個檔案。

  譯者應以註解的方式署名於文稿內，並照英文姓名或代號順序，列於文件的譯者欄。

  若某譯者未譯完負責章節，在其表達無力完成或擱置逾時並未予處理，而由另名譯者接手完成該章，則前者不可列名，惟後者列名；finisher takes all。

• 校對者 (reviser)：負責校稿，主要負責比較中文與原文，糾正譯稿中的錯誤。校對者也要負責維護詞彙的一致性。

  校對者也應列名，但不署名於文稿內，而列於獨立的說明文字中。出現順序依照英文姓名或代號。

• 潤飾者 (polisher)：也屬於校稿工作的一環，但主要負責修正中文譯稿文意不通之處，不需注重原文。潤飾者也要負責維護詞彙的一致性。

  潤飾者的 credit 與校對者同。

• 編輯 (editor)：負責總成每部 (volume) 文件的翻譯成果，包含文件的發佈。

細分工作種類，是為了讓更多同好可以參與 pydoccht 計畫；各人興趣不同，能力各異，可以選擇適合的工作進行。然而 pydoccht 也不可能有太多人手，並且大家都是利用閒暇時間來執行計畫，故身兼數角應是常態。

欲加入 pydoccht 的同好，請明白指出你想要幫忙的角色。目前的分工表紀錄在 http://wiki.python.org.tw/PythonProjects/pydoccht/JobTable。

執行模式

如同專業的翻譯工作，pydoccht 採用翻譯、校對、出版的執行模式。

pydoccht 雖是一個專案，但翻譯的對象 pydoc 本身是好幾部文件的集合。因此，翻譯工作會以一部完整的文件 (如 tutorial 即為一例) 為單位，分章翻譯、分章校對。

與台灣的專業電腦書籍翻譯不同的地方是：

1. 為了品質，我們真的要作校對。
2. 因應上游的更新，我們要有一套修訂作業流程。
3. 我們主要作網路出版，最多作到 PDF 出版，基本上不付印。

未來在本計畫漸次執行之後，本節會和本 README 的其它相關內容獨立寫成 pydoccht 的編輯手冊。

時程規畫

pydoccht 開始於 2007/Nov。初步預期於兩年內，即 2009 時完成所有文件的中譯。

初期先從 tutorial 開始翻譯，視情況漸次進行其它部分。

如何開始

首先你要取得 pydoccht 貯庫，請參見 REPOSITORY.rst 文檔。

所有的翻譯工作將在 chtdoc 下進行。目前 pydoccht 針對 trunk rev 58893 進行翻譯，原稿均置於 origdoc_r58893，而 chtdoc 是 hg cp origdoc_r58893 chtdoc 的結果。

Python 將會持續更新其文件。未來，在適當的時間點，新的文件會被拉進 pydoccht 貯庫，我們可以參考新 origdoc 與舊 origdoc 間的 diff，來對 chtdoc 進行修改。為了修改的效率，可能需要設計一些指令稿來輔助。

建構

clone 完成後，進入 chtdoc 目錄，執行 make html。Python doc framework 會自動建構 HTML 版的文件。另外，也可以用 make web 和 make htmlhelp 建構不同版本的文件成品。建好的文件將置於 build 目錄下。

根目錄下的檔案說明

• chtdoc: 繁體中文譯稿。未譯的部分是 origdoc_rREV 的複製檔。
• origdoc_rREV: revision 為 REV 的上游原文。
• clone.py: 協助取得上游文件與製作譯稿結構的指令稿。
• CONVENTION.rst: 翻譯文稿的慣例。
• README.rst: 本說明檔。
• REPOSITORY.rst: pydoccht 貯庫說明。
• glossary.rst: 詞彙表。