NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is maintained using a global network of volunteers. By posting this project on Transifex, GitHub, and other public places, and inviting you to participate, we are proposing an agreement that you will provide your improvements to Python's documentation or the translation of Python's documentation for the PSF's use under the CC0 license (available at https://creativecommons.org/publicdomain/zero/1.0/legalcode). In return, you may publicly claim credit for the portion of the translation you contributed and if your translation is accepted by the PSF, you may (but are not required to) submit a patch including an appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although nothing in this Documentation Contribution Agreement obligates the PSF to incorporate your textual contribution, your participation in the Python community is welcomed and appreciated.

You signify acceptance of this agreement by submitting your work to the PSF for inclusion in the documentation.

請注意: 以下基於 make 的便捷指令僅能運作於 Unix 系統上（無法使用並不影響主要翻譯流程），其他作業系統的使用者在翻譯後可考慮改於 GitHub Codespace 上呼叫 make 指令。 （參考 project wiki 頁面）

• 
  一個 GitHub 帳號
  
  
  安裝好 git︵Windows 上請參考 https://gitforwindows.org/︶
  
  
  一個 .po 檔的編輯器。推薦使用 Poedit，若熟悉po檔用一般文字編輯器亦可。
  
  
  參考 uv Installation 安裝uv，以便在本機端預覽翻譯成果。
  
  
  macOS 的使用者還需要先利用 homebrew 安裝 gettext，屆時 Sphinx 會使用到。
  

  brew install gettext
  brew link gettext --force

• 安裝 pre-commit 自動在 commit 時檢查 .po 檔格式。

  pip install pre-commit
  pre-commit install

在進行任何動作以前，你必須在 GitHub 上 fork 此專案（按下右上角的 Fork 按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork 進行修改。

請在 terminal 裡依照以下步驟：

# 用 git clone 將你的 fork 下載到本機端
git clone git@github.com:<你的 GitHub 帳號>/python-docs-zh-tw.git

# 進入 clone 下來的資料夾裡：
cd python-docs-zh-tw/

# 將 python/python-docs-zh-tw 設為 upstream remote
git remote add upstream https://github.com/python/python-docs-zh-tw.git

git fetch upstream
git checkout -b library/math upstream/3.13

make all

make lint

make build library/math.po

cd ../cpython/Doc/build/html
python3 -m http.server

open ../cpython/Doc/build/html/library/math.html

git add library/math.po
git commit -m "Working on library/math.po"

git push origin HEAD

git checkout library/math

git add library/math.po
git commit -m "fix(library/math): resolve review comments"
git push origin HEAD

這整個流程裡有幾件事情值得注意：

• 從 upstream（我們的主要 GitHub repo）做 fetch 的動作
• 對 origin（你的 fork）做 push
• 永遠不對 3.13 branch 進行修改，請保持讓這個 branch 唯讀，可以避免掉很多問題。

1. 
   譯文應兼顧前後文大意，在翻譯一份文件前請務必熟讀該文件的原文。
   
   
   中文句使用全形標點符號‥英文句維持半形的標點符號。
   
   例如‥﹁﹂︵︶、，。
   
   例如‥Python is supported by Python Software Foundation (PSF).
   
   
   中英文交雜時要插入空白‥符號英文間不用。
   
   例如‥使用 CPU 運算、使用﹁CPU﹂運算
   
   
   專有名詞應該參考術語表 Glossary 裡的翻譯方式。
   
   
   專有名詞可以選擇不翻譯。
   
   例如‥CPU、Unicode
   
   
   在翻譯名稱不常用或不確定的情形，宜用括號註解或直接保留原文。單頁只要首次出現有註解即可。
   
   例如‥正規表示式 (regular expression)
   
   例如‥Network News Transfer Protocol、Portable Network Graphics ︵可攜式網路圖形︶
   
   
   務必保留 reStructuredText 格式︵如‥超連結名稱︶
   
   
   po檔單行不應超過79字元寬度︵Poedit 會處理，但也可以使用 powrap 來確保格式︶
   
   
   高頻詞保留原文。因為翻譯後不一定能較好理解市面上 Python 的文章。 這些高頻詞在 Glossary 中的譯文仍保持原文，並加註市面上的翻譯。
   
   例如‥int、float、str、bytes、list、tuple、 dict、set、iterator、generator、iterable、 pickle
   

• :xxx:`...` 即為 reST 的語法，應該在譯文中保留。

  例如：

  Avoids tests using :func:`type` or :func:`isinstance`.

  翻譯為

  避免使用 :func:`type` 或 :func:`isinstance` 進行測試。

• reST 諸多語法需要保留前後的空白。在中文裡，該空白可以用 \\ 來取代，製造一個沒有寬度的分隔符號。

  例如當 :ref:`detail-instruction 部分會被編譯為中文時：

  For more information, please see :ref:`detail-instruction`.

  翻譯為

  更多資訊請參考\\ :ref:`detail-instruction`。

• 超連結語法該要在譯文中保留原字串。

  例如：

  `Documentation bugs`_ on the Python issue tracker

  應翻譯為

  Python issue tracker 上\\ `文件的錯誤 <Documentation bugs_>`_

  
  才能正確顯示為﹁Python issue tracker 上文件的錯誤﹂，並帶有正確連結且與前文才不會有多餘的空白。
  
  
  舉例中有程式碼時，前一段經常為 :: 結尾，此記號具有特殊意義，除了該段落結尾為冒號外，也代表下段縮排為程式碼。翻譯時應改為 ‥ ::︵參考 #568︶。
  
  例如‥
  

  Here is a code example::
  
    import sys
    print(sys.version)

  程式碼並不會出現在 po 檔之中，故在 po 檔中會顯示為

  Here is a code example::

  此時翻譯應為：

  以下是個程式範例： ::

• Discord channel discord.gg/44XheGXhWH
• Doc-SIG mailing list
• PEP 545
• zh_CN Translation of the Python Documentation
• Cambridge Dictionary

以下的指令皆預設在本機端 python-docs-zh-tw clone 的根目錄執行，同時預設在同一個目錄底下有一個 CPython clone，如下：

~/
├── python-docs-zh-tw/
└── cpython/

若要在本機端 clone 一個 CPython，可以使用以下指令：

$ git clone --depth 1 --no-single-branch https://github.com/python/cpython.git

這樣可以避免下載完整的 commit 歷史（對輸出文件沒什麼幫助），但仍然能把所有的 branch clone 下來。

pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (msgid) 跟其對應的空白翻譯字串 (msgstr)，此步驟會參考最新的 CPython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻譯字串但參考的 pot 檔的 msgid 已有變動，則此指令會自動加上 #, fuzzy 的標記，代表內容有些許差異需要更新。

$ make merge

$ make fuzzy

This translation project was created by Liang-Bo Wang in late-2015, the translations were hosted on https://docs.python.org.tw/3, and the project includes daily auto-build sever, documentation website enhancement for translations and project management on the python-doc-tw GitHub organisation. The translations were done on Transifex, with our own translation team and project. People who've contributed on this Transifex project are listed in TRANSLATORS

In mid-2018, thanks to PEP 545 and the Doc-SIG community, this project has migrated to Python's Github organisation and will become the official Taiwanese Mandarin translation of the documentation.

This translation project is highly influenced by python-doc-ja and python-doc-fr's translation architecture and workflow (i.e. a shameless copy). We truly appreciate their contributions.