新增繁體中文版README、CONTRIBUTING、設定語系檔；及日文版貢獻指南

Co-authored-by: corn323 <wingsky34@gmail.com>
2026-08-10 20:19:58 +08:00
parent a9f3c2c291
commit 49e92a5c41
8 changed files with 541 additions and 4 deletions
@@ -0,0 +1,100 @@
+為 Lophine 貢獻程式碼
+===============
+
+[English](./CONTRIBUTING_EN.md) | [中文（簡體）](./CONTRIBUTING.md) | **中文（繁體）** | [日本語](./CONTRIBUTING_JP.md)
+
+很高興你願意為這個專案貢獻！一般來說，我們對 PR 的審核標準相當寬鬆；
+如果你可以照著下面的規則來，我們就能更快完成審核。
+
+## 請使用個人帳號進行 Fork
+
+我們會定期嘗試合併現有的 PR，如果內容有一些小問題，我們會直接幫你修改後合併。
+
+但如果你的 PR 是用組織（organization）帳號 fork 出來的，我們就沒辦法直接修改你的 PR，只能先關閉、再手動合併一次。
+
+所以，請不要用組織帳號來 fork 這個專案！
+
+你可以參考[這個 Issue](https://github.com/isaacs/github/issues/1681)，了解為什麼我們沒辦法直接修改組織帳號的 PR。
+
+## 開發環境
+
+在開始寫程式之前，你需要先準備好以下開發工具與環境：
+
+- `git`
+- `JDK 25` 或更新版本
+
+特別提醒：動手之前，請先在你的作業系統與 Git 裡啟用長路徑（long path）支援，以下是部分平台的設定說明。
+
+[`Windows`](https://learn.microsoft.com/windows/win32/fileio/maximum-file-path-limitation)
+[`Git for Windows`](https://gitforwindows.org/faq.html#i-get-errors-trying-to-check-out-files-with-long-path-names)
+
+## 認識 Patch（補丁）系統
+
+Lophine 沿用了和 Folia 相同的 patch 系統，並依照修改的部分分成了兩個目錄：
+
+- `lophine-api` - 基於 `Folia-API` / `Paper-API` / `Spigot-API` / `Bukkit-API` 所做出的修改。
+- `lophine-server` - 針對 Minecraft 原版伺服器既有邏輯所做的修改。
+
+這套 patch 系統是以 git 為基礎運作的，你可以在這裡了解 git 的基本操作：<https://git-scm.com/docs/gittutorial>
+
+如果你已經 fork 了主要的 repository，接下來請照以下步驟操作：
+
+1. 把你 fork 出來的 repository clone 到本機；
+2. 在你的 IDE 或終端機（terminal）裡執行 Gradle 的 `applyAllPatches` 任務；如果是在終端機裡，可以直接執行 `./gradlew applyAllPatches`；
+3. 執行完成後，repository  的根目錄下應該會出現以下幾組目錄： `lophine-api` 與 `lophine-server`、`folia-api` 與 `folia-server` 以及 `paper-api` 與 `paper-server`（以下統稱為 `*-api` 與 `*-server`）；
+4. 進入 repository 根目錄下對應的 `*-api` 與 `*-server` 資料夾，在裡面進行修改。
+
+以下是對上述各個資料夾的簡單說明，更詳細的說明可以參考[這裡](https://github.com/Toffikk/paperweight-examples/blob/18241979c88068d5b061d95ad69c98ecb201c246/README.md)：
+
+1. API 部分
+
+- `lophine-api`：新增 API 的修改請放在這裡
+- `folia-api`：針對 Folia API 的修改請放在這個資料夾
+- `paper-api`：對於 Paper API / Spigot API / Bukkit API 的修改請放在這個資料夾
+
+2. Server 部分
+
+- `lophine-server`：針對 Minecraft 原版伺服器的修改、以及新增的檔案，都請放在這個資料夾
+- `folia-server`：針對 folia-server 的修改請放在這個資料夾
+- `paper-server`：根據 Paper 伺服器邏輯的修改請放在這個資料夾
+
+順帶一提，repository 根目錄下的 `*-api` 與 `*-server` 並不是一般的 git repository：
+
+- 在套用 patch 之前，base（基準點）指向的是未經修改的原始程式碼；
+- base 之後的每一個 commit，都會被視為一個 patch；
+- 只有在 Folia 最後一個 commit 之後的 commit，才會被視為是 Lophine 的 patch。
+
+## 新增 Patch
+
+依照以下步驟新增一個 patch 非常簡單：
+
+1. 在 `*-api` 與 `*-server` 裡進行修改；
+2. 用 git 把你的修改加入暫存區，例如執行 `git add .`（請不要把新建立的檔案一併加入）；
+3. 執行 `git commit -m <提交訊息>` 進行 commit；
+4. 執行 Gradle 任務 `fixupPaperApiFilePatches`，用於新建立的檔案產生對應的 patch 檔（注意：執行完之前先不要 commit）；
+5. 執行 Gradle 任務 `rebuildAllServerPatches`，用於把你的 commit 轉換成一個 patch；
+6. 把產生出來的 patch 檔 push 上去。
+
+完成以上步驟後，你就可以拿這些 patch 檔開 PR 提交了。
+
+## 修改 Patch
+
+你可以用以下方法來修改一個既有 patch 的內容：
+
+1. 直接在 HEAD 上進行修改；
+2. 執行 `git commit -a --fixup <hash>` ，做一個 fixup commit（請不要把 Lophine 新建立的檔案的修改一併 commit 進去）；
+   - 如果你想順便修改 commit 訊息，可以用 `--squash` 取代 `--fixup`。
+3. 執行 `git rebase -i --autosquash base` ，進行自動 rebase，接著只要輸入 `:q` 關掉確認頁面即可；
+4. 執行 Gradle 任務 `fixupPaperApiFilePatches`，用於重新產生 Lophine 新建立檔案的 patch（注意：執行完之前先不要 commit）；
+5. 執行 Gradle 任務 `rebuildAllServerPatches`，把修改套用到既有的 patch 上；
+6. 把修改後的 patch 重新 push 回去，再開一次 PR。
+
+## 為設定項目提供本地化的注解支援
+
+1. 在 `lophine-server/src/main/resources/assets/lophine/lang` 目錄下新增或修改對應語言的檔案，加入本地化的注解；
+   - 檔名請依照 <https://minecraft.wiki/w/Language> 頁面上列出的語言代碼來命名，例如 `en_us`、`zh_cn`、`zh_hk`、`zh_tw`，檔案格式為 `json`；
+2. 執行 Gradle 任務 `sortLangKeys`，把你修改的語言檔內容重新排序；
+3. 執行 `git commit -m <提交訊息>` 進行 commit；
+4. 把你修改的檔案 push 上去。
+
+完成以上步驟後，你就可以拿修改後的內容開 PR 提交了。