docs: add more detailed introduction to readme

grimmerk · grimmerk · commit c6f8ec3f731e · 2021-10-18T17:07:19.000+08:00
diff --git a/README.rst b/README.rst
@@ -64,16 +64,23 @@ the PSF for inclusion in the documentation.
 參與翻譯
 ========
 
-如何參與翻譯
+關於 po (Portable Object) 檔
+-----------------------------
+
+此為所需翻譯的文字檔，副檔名為 ``.po``，不同語系就會有一個 po 檔。主要內容為翻譯的參考原始字串 (*msgid*)，\
+及需要填入的翻譯字串 (*msgstr*)。有時你會看到 ``#, fuzzy`` 的註記，它代表此翻譯字串需要校閱。
+
+翻譯流程
 ------------
 
-**事先需要有：**
+事先需要有
+~~~~~~~~~~
 
 - 一個 `GitHub 帳號 <https://github.com/join>`_
 - `安裝好 git <https://help.github.com/articles/set-up-git/>`_\ （Windows
   上請參考 https://gitforwindows.org/）
-- 一個 ``.po`` 檔的編輯器，如果還沒有的話請使用 `poedit <https://poedit.net>`_
-- MacOS 的使用者還需要先利用 `homebrew <https://brew.sh/index_zh-tw>`_ 安裝 gettext ，屆時 Sphinx 會使用到。
+- 一個 ``.po`` 檔的編輯器。推薦使用 `Poedit <https://poedit.net>`_，若熟悉 po 檔用一般文字編輯器亦可。
+- macOS 的使用者還需要先利用 `homebrew <https://brew.sh/index_zh-tw>`_ 安裝 gettext ，屆時 Sphinx 會使用到。
 .. code-block:: bash
 
   brew install gettext
@@ -84,7 +91,10 @@ the PSF for inclusion in the documentation.
 按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork
 進行修改。
 
-在\ **第一次貢獻以前**\ （還沒有 clone 過），請在 terminal 裡依照以下步驟：
+第一次貢獻以前（還沒有 clone 過)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+請在 terminal 裡依照以下步驟：
 
 .. code-block:: bash
 
@@ -97,7 +107,10 @@ the PSF for inclusion in the documentation.
   # 將 python/python-docs-zh-tw 設為 upstream remote
   git remote add upstream https://github.com/python/python-docs-zh-tw.git
 
-在\ **每一次翻譯時**\ 請遵照以下步驟（`GitHub Flow`_）：
+每一次翻譯時
+~~~~~~~~~~~~
+
+請遵照以下步驟（`GitHub Flow`_）：
 
 .. _GitHub Flow: https://guides.github.com/introduction/flow/
 
@@ -106,27 +119,30 @@ the PSF for inclusion in the documentation.
 
 接著在 terminal 裡按照以下步驟：
 
-1. 基於最新版本的 ``upstream/3.9`` 開啟一個 branch，現在假設我們想要翻譯 Glossary
+1. 基於最新版本的 ``upstream/3.9`` 開啟一個 branch，現在假設我們想要翻譯 Glossary \
    所以把這個 branch 叫做 ``glossary`` ::
 
     git fetch upstream
     git checkout -b glossary upstream/3.9
 
-2. 接著就可以開始翻譯，你可以使用 Poedit 應用程式將檔案打開，或是用以下指令\
-   （翻譯不同檔案時將 glossary 換成別的檔名） ::
+2. 接著就可以開始翻譯，你可以手動開啟 Poedit 應用程式再選檔案或用以下指令請 Poedit 將檔案\
+   打開，翻譯不同檔案時將 glossary 換成別的檔名） ::
 
     poedit glossary.po
 
-3. 存檔以後，可以輸出文件以確保你的修改沒有 rST 的語法錯誤或警告 ::
+3. 存檔以後，執行以下列指令編譯輸出文件，以確保你的修改沒有 rST 的語法錯誤或警告 ::
 
     make
 
-   這個過程中 Sphinx 會幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning
+   如果你還沒有執行 `維護、預覽`_ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\
+   並且會使用 Sphinx 幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning \
    的狀態，因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合\
    `翻譯守則`_
 
-4. 在瀏覽器中打開編譯出來的文件以確認整份文件的語意通暢\
-   （翻譯別的檔案時將 glossary 換成別的檔名） ::
+4. 輸出的文件會被放置在您的本地端 CPython clone（見 `維護、預覽`_ 段落的圖示）\
+   底下的 ``Doc/build/html``，切換到該目錄再使用 ``python3 -m http.server`` \
+   或類似的靜態網頁伺服器即可以預覽成果。你可以執行下列指令請瀏覽器打開編譯出來的文件\
+   以確認整份文件的語意通暢（翻譯別的檔案時將 glossary 換成別的檔名） ::
 
     open ../cpython/Doc/build/html/glossary.html
 
@@ -165,7 +181,9 @@ the PSF for inclusion in the documentation.
 要翻譯哪些東西
 --------------
 
-最簡單的貢獻方式就是更新 *fuzzy entries*，讓翻譯的內容保持與最新版本的文件\
+主要是填入翻譯字串 (*msgid*) 以及更新有標記為 ``#, fuzzy`` 的字串。
+
+其中最簡單的貢獻方式就是更新 *fuzzy entries*，讓翻譯的內容保持與最新版本的文件\
 同步。請參考 `尋找 fuzzy entries`_ 段落。
 
 此外，當前的目標為完成 **Tutorial** 的翻譯，因此在 ``tutorial/`` 底下的所有
@@ -382,11 +400,12 @@ type                  型別
 這樣可以避免下載完整的 commit 歷史（對輸出文件沒什麼幫助），但仍然能把所有的
 branch clone 下來。
 
-與 CPython 同步最新的 pot 檔
-----------------------------
+與 CPython 同步最新的 pot 檔 (目前由 GitHub Actions 代為執行)
+----------------------------------------------------------
 
 pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*) 跟其對應的空白翻譯字串 (*msgstr*)，\
-此步驟會更新 po 檔，我們在 po 檔的每一個 (*msgstr*) 填上翻譯。
+此步驟會參考最新的 Cpython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻議字串但參考的 \
+pot 檔的 ``msgid`` 已有變動，則此指令會自動加上 ``#, fuzzy`` 的標記，代表內容有些許差異需要更新。
 
 .. code-block:: bash
 
@@ -395,26 +414,13 @@ pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*)
 尋找 fuzzy entries
 ------------------
 
-*Fuzzy entries* 是指更新 po 檔的原始字串（*msgid*）以後，大部分內容相同但有\
-些許差異的字串，即表示該字串的翻譯需要更新。在 po 檔中，您會看到 ``#, fuzzy``
-的字樣，這就表示了接下來的字串是 fuzzy entry，需要更新翻譯。
+在 po 檔中，您會看到 ``#, fuzzy`` 的字樣，這就表示了接下來的字串是 fuzzy entry，需要更新翻譯。\
+執行下列指令會列出有 *Fuzzy entries* 的檔案。
 
 .. code-block:: bash
 
   $ make fuzzy
 
-本地端編譯輸出文件
-------------------
-
-輸出的文件會被放置在您的本地端 CPython clone（見 `維護、預覽`_ 段落的圖示）\
-底下的 ``Doc/build/html``，切換到該目錄再使用 ``python3 -m http.server``
-或類似的靜態網頁伺服器即可以預覽成果。編譯程序則使用：
-
-.. code-block:: bash
-
-  $ make
-
-
 Project History
 ===============
 
