From c6f8ec3f731e2823589603a882ded7d2f76f228a Mon Sep 17 00:00:00 2001 From: grimmer Date: Mon, 18 Oct 2021 16:34:30 +0800 Subject: [PATCH 1/6] docs: add more detailed introduction to readme --- README.rst | 70 +++++++++++++++++++++++++++++------------------------- 1 file changed, 38 insertions(+), 32 deletions(-) diff --git a/README.rst b/README.rst index 48c5a4ff2c..50f21cc437 100644 --- 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 帳號 `_ - `安裝好 git `_\ （Windows 上請參考 https://gitforwindows.org/） -- 一個 ``.po`` 檔的編輯器，如果還沒有的話請使用 `poedit `_ -- MacOS 的使用者還需要先利用 `homebrew `_ 安裝 gettext ，屆時 Sphinx 會使用到。 +- 一個 ``.po`` 檔的編輯器。推薦使用 `Poedit `_，若熟悉 po 檔用一般文字編輯器亦可。 +- macOS 的使用者還需要先利用 `homebrew `_ 安裝 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 =============== From 1f1fbbcc663d1da157f334897673320fb64c8ff3 Mon Sep 17 00:00:00 2001 From: grimmer Date: Thu, 21 Oct 2021 11:51:53 +0800 Subject: [PATCH 2/6] docs: update the sentences about searching fuzzy entries --- README.rst | 13 +++++++------ library/heapq.po | 5 ----- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 50f21cc437..5a0ce5eab1 100644 --- a/README.rst +++ b/README.rst @@ -183,8 +183,8 @@ the PSF for inclusion in the documentation. 主要是填入翻譯字串 (*msgid*) 以及更新有標記為 ``#, fuzzy`` 的字串。 -其中最簡單的貢獻方式就是更新 *fuzzy entries*，讓翻譯的內容保持與最新版本的文件\ -同步。請參考 `尋找 fuzzy entries`_ 段落。 +其中最簡單的貢獻方式就是更新 *fuzzy entries*，讓曾經翻譯的內容保持與最新版本的文件\ +同步。請參考 `尋找有翻譯過但需校閱的 fuzzy entries`_ 段落。 此外，當前的目標為完成 **Tutorial** 的翻譯，因此在 ``tutorial/`` 底下的所有 po 檔皆為首要的翻譯對象。您也可以幫忙校對已經翻譯過的內容。 @@ -400,7 +400,7 @@ type 型別 這樣可以避免下載完整的 commit 歷史（對輸出文件沒什麼幫助），但仍然能把所有的 branch clone 下來。 -與 CPython 同步最新的 pot 檔 (目前由 GitHub Actions 代為執行) +與 CPython 同步最新的 pot 檔 (目前由 GitHub Actions 定時代為執行) ---------------------------------------------------------- pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*) 跟其對應的空白翻譯字串 (*msgstr*)，\ @@ -411,11 +411,12 @@ pot 檔的 ``msgid`` 已有變動，則此指令會自動加上 ``#, fuzzy`` 的 $ make merge -尋找 fuzzy entries ------------------- +尋找有翻譯過但需校閱的 fuzzy entries +--------------------------------- 在 po 檔中，您會看到 ``#, fuzzy`` 的字樣，這就表示了接下來的字串是 fuzzy entry，需要更新翻譯。\ -執行下列指令會列出有 *Fuzzy entries* 的檔案。 +您可以自行用習慣的文字編輯器、Linux 指令搜尋有包含此字樣的檔案，但請記得 ``#, fuzzy`` 標記的翻譯字串\ +有可能是尚未翻譯過的空白字串 (*msgstr*)。執行下列指令會列出有 *Fuzzy entries* 的檔案且會排除這個情形。 .. code-block:: bash diff --git a/library/heapq.po b/library/heapq.po index 58d9f15ea4..c487b019c7 100644 --- a/library/heapq.po +++ b/library/heapq.po @@ -188,8 +188,6 @@ msgid "" "to ``sorted(itertools.chain(*iterables), reverse=True)``, all iterables must " "be sorted from largest to smallest." msgstr "" -"*reverse* 是一個布林值。如果設定為 ``True`` ，那輸入的元素被 merge 時每一個比" -"較結果都是相反的。" #: ../../library/heapq.rst:107 msgid "Added the optional *key* and *reverse* parameters." @@ -218,9 +216,6 @@ msgid "" "example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key)[:" "n]``." msgstr "" -"回傳一個包含資料 *iterable* 中前 *n* 小元素的 list 。如果有指定 *key* 參數，" -"*key* 會是只有一個參數的函式，用來從每一個 *iterable* 的元素中決定一個比較的" -"依據：``key=str.lower`` 等價於 ``sorted(iterable, key=key)[:n]``" #: ../../library/heapq.rst:128 msgid "" From 1200b89e6e5e03cbdd0730627d9c4c2eed0f7adf Mon Sep 17 00:00:00 2001 From: "Matt.Wang" Date: Thu, 21 Oct 2021 14:07:25 +0800 Subject: [PATCH 3/6] fix(README): wrong Telegram invitation link --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 5a0ce5eab1..f115795992 100644 --- a/README.rst +++ b/README.rst @@ -362,7 +362,7 @@ type 型別 幫助，則可以使用 Telegram_。 .. _Issue: https://github.com/python-doc-tw/python-docs-zh-tw/issues -.. _Telegram: https://t.me/PyDocT +.. _Telegram: https://t.me/PyDocTW 另外，此翻譯的 coordinator 為 `adrianliaw `_，\ 您也可以透過此 email 聯繫：``adrianliaw2000 at gmail dot com``。 From 80e1d32c6a76db8a1fc47346deceb315d512dbee Mon Sep 17 00:00:00 2001 From: grimmer Date: Thu, 21 Oct 2021 15:22:17 +0800 Subject: [PATCH 4/6] docs: correct some typo --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index f115795992..1678698859 100644 --- a/README.rst +++ b/README.rst @@ -80,7 +80,7 @@ the PSF for inclusion in the documentation. - `安裝好 git `_\ （Windows 上請參考 https://gitforwindows.org/） - 一個 ``.po`` 檔的編輯器。推薦使用 `Poedit `_，若熟悉 po 檔用一般文字編輯器亦可。 -- macOS 的使用者還需要先利用 `homebrew `_ 安裝 gettext ，屆時 Sphinx 會使用到。 +- macOS 的使用者還需要先利用 `homebrew `_ 安裝 gettext，屆時 Sphinx 會使用到。 .. code-block:: bash brew install gettext @@ -404,7 +404,7 @@ branch clone 下來。 ---------------------------------------------------------- pot 檔為翻譯的樣板檔案，它包含需要翻譯的原始字串 (*msgid*) 跟其對應的空白翻譯字串 (*msgstr*)，\ -此步驟會參考最新的 Cpython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻議字串但參考的 \ +此步驟會參考最新的 CPython 中的 pot 檔來更新 po 檔。如果是之前在 po 檔中已填入過翻議字串但參考的 \ pot 檔的 ``msgid`` 已有變動，則此指令會自動加上 ``#, fuzzy`` 的標記，代表內容有些許差異需要更新。 .. code-block:: bash From 78ab3d7387968bed0078c5ab67d78c1ca8368b3e Mon Sep 17 00:00:00 2001 From: grimmer Date: Thu, 21 Oct 2021 15:23:20 +0800 Subject: [PATCH 5/6] docs: add back some heapq translations which were accidentally deleted --- library/heapq.po | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/library/heapq.po b/library/heapq.po index c487b019c7..58d9f15ea4 100644 --- a/library/heapq.po +++ b/library/heapq.po @@ -188,6 +188,8 @@ msgid "" "to ``sorted(itertools.chain(*iterables), reverse=True)``, all iterables must " "be sorted from largest to smallest." msgstr "" +"*reverse* 是一個布林值。如果設定為 ``True`` ，那輸入的元素被 merge 時每一個比" +"較結果都是相反的。" #: ../../library/heapq.rst:107 msgid "Added the optional *key* and *reverse* parameters." @@ -216,6 +218,9 @@ msgid "" "example, ``key=str.lower``). Equivalent to: ``sorted(iterable, key=key)[:" "n]``." msgstr "" +"回傳一個包含資料 *iterable* 中前 *n* 小元素的 list 。如果有指定 *key* 參數，" +"*key* 會是只有一個參數的函式，用來從每一個 *iterable* 的元素中決定一個比較的" +"依據：``key=str.lower`` 等價於 ``sorted(iterable, key=key)[:n]``" #: ../../library/heapq.rst:128 msgid "" From da179b880fa80a8708e023e449e6f60fb5be9fd8 Mon Sep 17 00:00:00 2001 From: Grimmer Date: Thu, 21 Oct 2021 22:42:30 +0800 Subject: [PATCH 6/6] Update README.rst Co-authored-by: Josix --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 1678698859..50cfb9b64d 100644 --- a/README.rst +++ b/README.rst @@ -125,7 +125,7 @@ the PSF for inclusion in the documentation. git fetch upstream git checkout -b glossary upstream/3.9 -2. 接著就可以開始翻譯，你可以手動開啟 Poedit 應用程式再選檔案或用以下指令請 Poedit 將檔案\ +2. 接著就可以開始翻譯（翻譯時可參考`翻譯守則`_），你可以手動開啟 Poedit 應用程式再選檔案或用以下指令請 Poedit 將檔案\ 打開，翻譯不同檔案時將 glossary 換成別的檔名） :: poedit glossary.po