Skip to content

基礎知識

Jump to bottom
RockLeon edited this page Aug 30, 2023 · 1 revision

第 1 步：事前準備、須知

關於 po (Portable Object) 檔

此為所需翻譯的文字檔，副檔名為 .po，不同語系就會有一個 po 檔。
主要內容為翻譯的參考原始字串 (msgid)，及需要填入的翻譯字串 (msgstr)。
有時你會看到 #, fuzzy 的註記，它代表此翻譯字串需要校閱。

請先準備好下列事項：

  • 一個 GitHub 帳號
  • 安裝好 git （Windows 上請參考 https://gitforwindows.org/ ）
  • 一個 .po 檔的編輯器。推薦使用 Poedit，若熟悉 po 檔用一般文字編輯器亦可。
  • 在 GitHub 上 fork 此專案（按下右上角的 Fork 按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork 進行修改。

⚠️ macOS 的使用者

  • 請利用 homebrew 安裝 gettext，屆時 Sphinx 會使用到。
  brew install gettext
  brew link gettext --force

⚠️ Windows (非 Unix 系統) 的使用者

  • 請注意: 以下基於 make 的便捷指令僅能運作於 Unix 系統上（無法使用並不影響主要翻譯流程）
  • 可考慮改於 GitHub Codespace 上呼叫 make 指令，進行網站編譯。
  • 或者研究安裝 WSL (e.g., Ubuntu WSL)

第 2 步： Clone Repo

請在 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

第 3 步：每一次翻譯時

註：本步驟可以疊代❤️

請遵照以下步驟 GitHub Flow：

新增一個 issue，如：「翻譯 tutorial/introduction.po」，
讓大家知道你正在翻譯這個檔案。

另外，也可以使用 make todo 列出尚待翻譯的檔案。

接著在 terminal 裡按照以下步驟：

  1. 基於最新版本的 upstream/3.12 開啟一個 branch，現在假設我們想要翻譯 Glossary
    所以把這個 branch 叫做 glossary

      git fetch upstream
  git checkout -b glossary upstream/3.12

  2. 接著就可以開始翻譯（翻譯時可參考 翻譯守則 ），你可以手動開啟 Poedit 應用程式再選檔案或用以下指令請 Poedit 將檔案
    打開，翻譯不同檔案時將 glossary 換成別的檔名）

      poedit glossary.po

  3. 存檔以後，執行以下列指令編譯輸出文件，以確保你的修改沒有 rST 的語法錯誤或警告

      VERSION=3.12 make all

    如果你還沒有執行 維護、預覽 的 clone CPython 的動作，此指令會自動幫你 clone CPython，
    並且會使用 Sphinx 幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning 的狀態，
    因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合翻譯守則

  4. 輸出的文件會被放置在你的本地端 CPython clone（見 維護、預覽_ 段落的圖示）
    底下的 Doc/build/html，切換到該目錄再使用 python3 -m http.server
    或類似的靜態網頁伺服器即可以預覽成果。你可以執行下列指令請瀏覽器打開編譯出來的文件
    以確認整份文件的語意通暢（翻譯別的檔案時將 glossary 換成別的檔名）

      open ../cpython/Doc/build/html/glossary.html

  5. 檢查完畢後，即可以將你的翻譯 commit 起來，請使用明確的 commit message

      git add glossary.po
  git commit -m "Working on glossary."

  6. 將你的修改 push 到你的 GitHub clone 上。為了簡單，我們可以用 origin HEAD 來告訴 git 我們將修改 push 到 origin，branch 則和本機端的 branch 名稱一樣

      git push origin HEAD

  7. 這時候你就可以打開一個 pull request 了，請打開專案的 repo，
    你會看到一個「Compare & Pull Request」按鈕，按下它就可以對此專案發送一個 pull request。

  8. 如果有人在 GitHub 上 review 了你的 pull request，並且你想要修改你的內容，
    那麼（如果你切換到了別的 branch 上）你要先切換回到你的 branch 上

      git checkout glossary

    接著修改你要修正的問題，並再次 commit、push

      git add glossary.po
  git commit -m "glossary: small fixes"
  git push origin HEAD
Clone this wiki locally