@@ -6,13 +6,11 @@ Python 官方說明文件臺灣繁體中文翻譯計畫
66:target: https://t.me/PyDocTW
77:alt: Join Chat on Telegram
88
9- 本 GitHub repository 含有 Python 官方說明文件的 zh_TW 翻譯。實際的翻譯內容\
10- 在這個 repository 裡以 Python 的穩定發行版本作為 branch 名稱，請參考 3.7 等
11- branch 以查看目前的翻譯內容。此 master branch 則為專案的貢獻說明。
9+ 這是 Python 3.7 官方說明文件的臺灣繁體中文（zh_TW）翻譯。
1210
13- 您可以在 https://python-doc-tw.github.io/ 瀏覽目前翻譯的成果。目前以
14- Python 3.7 為翻譯的對象，** 暫時不考慮 Python 2.7 的翻譯工作 **。未來有新的
15- Python 發行版本時，也將會將翻譯滾動至新的版本 。
11+ 翻譯之前，請務必詳讀並同意 \ ` 授權與 License `_。參與方式請參考 \ ` 參加翻譯 `_。
12+
13+ 您可以在 https://python-doc-tw.github.io/ 瀏覽目前翻譯的成果 。
1614
1715想問問題、認識翻譯同好，歡迎加入 Telegram 聊天室 `t.me/PyDocTW `_
1816
@@ -69,65 +67,87 @@ the PSF for inclusion in the documentation.
6967如何參加翻譯
7068------------
7169
72- 實際的翻譯即為修改 po 檔，流程遵照標準的 `GitHub Flow
73- <https://guides.github.com/introduction/flow/> `_，並且在翻譯任何部份以前新增\
74- 一個 issue 並且指定給自己，讓大家知道您正在翻譯該部分。詳細的步驟如下：
75-
76- - `新增一個 issue <https://github.com/python/python-docs-zh-tw/issues >`_ 並
77- assign 給自己，如：「翻譯 tutorial/introduction.po」
78- - 在 GitHub 上 fork 此專案
79- - 將您的 fork clone 一份到本機端
80- - 新增一個 branch，所有新的變更將在這個 branch 上完成
81- - 修改 po 檔的內容（參考下面的段落）
82- - commit 您所修改的內容並且 push 到 GitHub
83- - 對本專案發出 *Pull Request *
70+ **事先需要有： **
8471
85- 編輯 po 檔的方式主要可以分為兩種，以 Transifex 作為工具或是使用其他翻譯工具：
72+ - 一個 `GitHub 帳號 <https://github.com/join >`_
73+ - `安裝好 git <https://help.github.com/articles/set-up-git/ >`_\ （Windows
74+ 上請參考 https://gitforwindows.org/）
75+ - 一個 ``.po `` 檔的編輯器，如果還沒有的話請使用 `poedit <https://poedit.net >`_
8676
87- 1. 使用 Transifex 作為翻譯工具（不建議）
88- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77+ 在進行任何動作以前，你必須在 GitHub 上 fork 此專案（按下右上角的 ``Fork ``
78+ 按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork
79+ 進行修改。
8980
90- 您可以註冊 Transifex 帳號並申請加入官方的 `Transifex 專案
91- <https://www.transifex.com/python-doc/python-newest> `_，並且在上面\
92- 編輯您所要翻譯的頁面，並且在您本機上透過 command line 從此專案的 clone 的\
93- 根目錄位置執行以下指令：
81+ 在\ **第一次貢獻以前 **\ （還沒有 clone 過），請在 terminal 裡依照以下步驟：
9482
9583..code-block ::bash
9684
97- $ ./txpull< po 檔的路徑>
85+ # 用 git clone 將你的 fork 下載到本機端
86+ git clone git@github.com:< 你的 GitHub 帳號> /python-docs-zh-tw.git
9887
99- transifex-client `` 和 ``poindent ``，|gettext |_、
100- ``tac `` 等指令。這個小工具可以幫您把您在 Transifex 上針對特定檔案的翻譯 pull
101- 下來，並且修正換行格式的錯誤。您在使用 txpull 以後就可以 commit 以及 push 了。
88+ # 進入 clone 下來的資料夾裡：
89+ cd python-docs-zh-tw/
10290
103- .. | gettext | replace :: `` gettext ``
104- .. _ gettext : https://www.gnu.org/software/gettext/
91+ # 將 python/python-docs-zh-tw 設為 upstream remote
92+ git remote add upstream https://github.com/python/python-docs-zh-tw.git
10593
106- 2. 使用其他翻譯工具（建議）
107- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
94+ \ **每一次翻譯時 **\ 請遵照以下步驟（`GitHub Flow `_）：
10895
109- 您可以使用以下工具在本機端翻譯 po 檔內容：
96+ .. _ GitHub Flow : https://guides.github.com/introduction/flow/
11097
111- - 推薦：`poedit <https://www.poedit.net/ >`_
112- - gted
113- - gtranslator
114- - lokalize
115- - betterpoeditor
116- - 適當模式底下的 vim 或 emacs
117- - Vé on Android
118- - 可能還有更多其他的
98+ 首先，`新增一個 issue <https://github.com/python/python-docs-zh-tw/issues >`_\
99+ ，如：「翻譯 tutorial/introduction.po」，讓大家知道您正在翻譯這個檔案。
119100
120- 編輯完檔案以後，請執行以下指令以確保檔案的換行格式一致（需要安裝
121- |poindent |_ ：``pip install poindent ``）：
101+ 接著在 terminal 裡按照以下步驟：
122102
123- .. | poindent | replace :: `` poindent ``
124- .. _ poindent : https://pypi.org/project/poindent/
103+ 1. 基於最新版本的 `` upstream/3.7 `` 開啟一個 branch，現在假設我們想要翻譯 Glossary
104+ 所以把這個 branch 叫做 `` glossary `` ::
125105
126- ..code-block ::bash
106+ git fetch upstream
107+ git checkout -b glossary upstream/3.7
108+
109+ 2. 接著就可以開始翻譯，你可以使用 Poedit 應用程式將檔案打開，或是用以下指令\
110+ （翻譯不同檔案時將 glossary 換成別的檔名） ::
111+
112+ poedit glossary.po
113+
114+ 3. 存檔以後，可以輸出文件以確保你的修改沒有 rST 的語法錯誤或警告 ::
115+
116+ make
117+
118+ 這個過程中 Sphinx 會幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning
119+ 的狀態，因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合\
120+ `翻譯守則`_
121+
122+ 4. 在瀏覽器中打開編譯出來的文件以確認整份文件的語意通暢\
123+ （翻譯別的檔案時將 glossary 換成別的檔名） ::
124+
125+ open ../cpython/Doc/build/html/glossary.html
126+
127+ 5. 檢查完畢後，即可以將你的翻譯 commit 起來，請使用明確的 commit message ::
128+
129+ git add glossary.po
130+ git commit -m "Working on glossary."
131+
132+ 6. 將你的修改 push 到你的 GitHub clone 上。為了簡單，我們可以用 ``origin HEAD ``
133+ 來告訴 git 我們將修改 push 到 origin，branch 則和本機端的 branch 名稱一樣 ::
134+
135+ git push origin HEAD
136+
137+ 7. 這時候你就可以打開一個 pull request 了，請打開
138+ https://github.com/python/python-docs-zh-tw，你會看到一個「Compare & Pull
139+ Request」按鈕，按下它就可以對此專案發送一個 pull request。
140+
141+ 8. 如果有人在 GitHub 上 review 了你的 pull request，並且你想要修改你的內容，\
142+ 那麼（如果你切換到了別的 branch 上）你要先切換回到你的 branch 上 ::
143+
144+ git checkout glossary
127145
128- $ poindent < po 檔的路徑 >
146+ 接著修改你要修正的問題，並再次 commit、push ::
129147
130- poindent `` 以後即可 commit、push 等。
148+ git add glossary.po
149+ git commit -m "glossary: small fixes"
150+ git push origin HEAD
131151
132152
133153要翻譯哪些東西
@@ -143,7 +163,7 @@ po 檔皆為首要的翻譯對象。您也可以幫忙校對已經翻譯過的
143163翻譯守則
144164========
145165
146- #. 譯文應兼顧前後文大意。
166+ #. 譯文應兼顧前後文大意，在翻譯一份文件前請務必熟讀該文件的原文 。
147167
148168#. 中文句使用全形標點符號；英文句維持半形的標點符號。
149169
@@ -171,7 +191,8 @@ po 檔皆為首要的翻譯對象。您也可以幫忙校對已經翻譯過的
171191
172192#. 務必保留 reStructuredText 格式（如：超連結名稱）
173193
174- #. po 檔單行不應超過 79 字元寬度（可以使用 |poindent |_ 來確保格式）
194+ #. po 檔單行不應超過 79 字元寬度（Poedit 會處理，但也可以使用 `poindent
195+ <https://pypi.org/project/poindent/> `_ 來確保格式）
175196
176197#. 高頻詞保留原文。因為翻譯後不一定能較好理解市面上 Python 的文章。 這些高頻詞\
177198 在 Glossary 中的譯文仍保持原文，並加註市面上的翻譯。
@@ -322,6 +343,9 @@ type 型別
322343- Telegram group `t.me/PyDocTW `_
323344- `Doc-SIG mailing list <https://mail.python.org/mailman/listinfo/doc-sig >`_
324345- `PEP 545 <https://www.python.org/dev/peps/pep-0545/ >`_
346+ - `zh_CN Translation of the Python Documentation
347+ <https://zhsj.github.io/python-docs-zh-cn/> `_
348+ - `Cambridge Dictionary <https://dictionary.cambridge.org/ >`_
325349
326350
327351維護、預覽