貢獻指南

June 20, 2026 · View on GitHub

感謝您對 OpenCC 專案的貢獻！本文件說明如何為 OpenCC 貢獻詞典條目、撰寫測試並確保程式碼品質。

授權

OpenCC 以 Apache License 2.0 釋出。提交 Pull Request、issue/comment、郵件 patch、詞典條目、測試案例或其他形式的貢獻，即表示您確認自己有權提交這些內容，並同意您的貢獻也依 Apache License 2.0 授權釋出。

目錄

新增詞典條目

新增地區慣用詞前，請先閱讀 OpenCC 地區詞收錄標準。該標準說明哪些地區詞適合收錄、需要提供哪些依據，以及應如何避免高風險誤轉換。

1. 選擇正確的詞典檔案

詞典檔案位於 data/dictionary/ 目錄下，根據轉換類型選擇對應的檔案：

  • 簡繁轉換

    • STCharacters.txt - 簡體到繁體（單字）
    • STPhrases.txt - 簡體到繁體（詞組）
    • TSCharacters.txt - 繁體到簡體（單字）
    • TSPhrases.txt - 繁體到簡體（詞組）

  • 臺灣正體用詞

    • TWVariants.txt - 臺灣異體字
    • TWVariantsPhrases.txt - 轉入臺灣字形（如 s2tw、s2twp、t2tw）時使用的臺灣異體字詞組例外
    • TWVariantsRevPhrases.txt - 從臺灣字形轉出（如 tw2s、tw2sp、tw2t）時使用的臺灣異體字詞組例外
    • TWPhrases.txt - 臺灣慣用詞

  • 香港繁體用詞

    • HKVariants.txt - 香港異體字
    • HKVariantsPhrases.txt - 轉入香港字形（如 s2hk、t2hk）時使用的香港異體字詞組例外
    • HKVariantsRevPhrases.txt - 從香港字形轉出（如 hk2s、hk2t）時使用的香港異體字詞組例外

  • 日文新舊字形（僅供探索性研究，不建議用於生產環境）

    • JPShinjitaiCharacters.txt - 日文新舊字體對照（單字）
    • JPShinjitaiPhrases.txt - 日文新字體到舊字體（詞組，亦包含少量和製漢語詞匯轉換）

2. 詞典格式規範

詞典檔案使用 Tab 字元（\t）分隔來源詞與目標詞，請勿使用空格。

格式：來源詞<TAB>目標詞

範例：

虚伪叹息	虛偽嘆息
潮湿灶台	潮濕灶台
赞叹	讚歎

如果一個來源詞對應多個可能的目標詞，使用空格分隔：

一出	一齣 一出

3. 編輯詞典

使用文字編輯器開啟對應的 .txt 檔案，新增您的詞條。請確保：

  1. 使用 Tab 字元（\t）分隔來源詞與目標詞
  2. 每行一個條目
  3. 檔案使用 UTF-8 編碼

4. 檢查字級規則與詞表依賴

詞組級詞表如果仍保留逐字的 A -> B 轉換，對應的字級詞表也必須顯式 保留 A 的 B 候選。若一般情況下不應再把 A 預設轉為 B，請不要 直接刪除字級關係；應改為非預設候選，例如 A<TAB>A B。這樣單字預設 仍保留為 A，但詞表中的 A -> B 依賴不會變成隱式規則。

修改 STCharacters.txt、TSCharacters.txt、TWVariants.txt、 HKVariants.txt 或其對應詞組詞表時，請同步檢查詞組中逐字對齊的 替換是否仍在字表候選中。可執行以下測試檢查這類字級依賴：

bazel test //data/dictionary:dictionary_phrase_character_dependency_test

排序詞典

重要：詞典檔案必須按字典序排序，否則測試會失敗。

使用排序工具

專案提供了自動排序工具，位於 data/scripts/ 目錄：

排序單一檔案

python3 data/scripts/sort.py data/dictionary/STPhrases.txt

這會直接排序並覆蓋原檔案。如果想輸出到其他檔案：

python3 data/scripts/sort.py data/dictionary/STPhrases.txt data/dictionary/STPhrases_sorted.txt

排序所有詞典檔案

python3 data/scripts/sort_all.py data/dictionary

這會自動排序 data/dictionary/ 目錄下所有 .txt 檔案。

排序檢查

排序是否正確會在測試時自動檢查。如果詞典未排序或包含重複的鍵，DictionaryTest 會報錯：

[ FAILED ] DictionaryTest/STPhrases.UniqueSortedTest
STPhrases is not sorted.

遇到此錯誤時，請執行排序工具重新排序。

執行測試

OpenCC 同時維護 CMake、Bazel 與 Node.js 建置/測試流程。詞典與轉換行為修改通常至少需要跑 Bazel 測試；C++ CLI、插件或包裝相關修改也應跑對應的 CMake 或 npm 測試。

安裝 Bazel

macOS

brew install bazel

Ubuntu/Debian

sudo apt install bazel

或參考 Bazel 官方安裝指南。

其他作業系統

請參考 Bazel 安裝文件 獲取適合您系統的安裝方式。

Bazel 測試

bazel test --test_output=errors //src/... //data/... //test/... //python/...

如果修改了 jieba 插件或 golden 輸出，也請加入相關目標：

bazel test --test_output=errors //plugins/jieba/... //test/golden:golden_convert_test

常用的特定測試：

bazel test //data/dictionary/...
bazel test //data/config:config_dict_validation_test
bazel test //test:command_line_converter_test

CMake 測試

本地 C++ 開發可使用 CMake：

cmake -S . -B build -DENABLE_GTEST=ON
cmake --build build
ctest --test-dir build --output-on-failure

如需測試 optional jieba plugin：

cmake -S . -B build -DENABLE_GTEST=ON -DBUILD_OPENCC_JIEBA_PLUGIN=ON
cmake --build build
ctest --test-dir build --output-on-failure

Node.js 測試

Node.js binding 與 npm CLI 修改請執行：

npm install
npm test

驗證 npm prebuild 佈局時：

npm run prebuild
PREBUILDS_ONLY=1 npm test

測試輸出

  • --test_output=all：顯示所有測試輸出
  • --test_output=errors：僅顯示失敗的測試

撰寫測試案例

測試驅動開發流程

在修改詞典前，建議先撰寫測試案例，遵循測試驅動開發（TDD）流程：

  1. 先寫測試：在 test/testcases/testcases.json 新增測試案例
  2. 確認測試失敗：執行測試，確認新案例因為詞典未更新而失敗
  3. 修改詞典：新增或修改詞典條目
  4. 測試通過：再次執行測試，確認修改後測試通過

這樣可以確保您的修改確實達到預期效果。

測試案例格式

測試案例定義於 test/testcases/testcases.json，格式如下：

{
  "cases": [
    {
      "id": "英文簡要描述這個測試是修復或解決什麼問題的",
      "input": "輸入內容",
      "expected": {
        "s2t": "預期的簡轉繁輸出",
        "s2tw": "預期的簡轉臺灣正體輸出",
        "t2s": "預期的繁轉簡輸出",
        ...
      }
    }
  ]
}

欄位說明

  • id：唯一的測試案例識別碼，可使用 case_ 前綴加流水號，或 OpenCC_Issue_1234 等
  • input：輸入文字
  • expected：各種轉換配置的預期輸出
    • 僅需包含您要測試的轉換配置
    • 可以同時測試多種配置

使用腳本生成測試案例

專案提供 scripts/add_testcase.py，可根據目前建置出的 OpenCC 與詞典，自動為 test/testcases/testcases.json 生成一筆測試案例。此工具適合在已完成詞典修改後， 快速補齊多個常用配置的 expected 輸出；提交前仍需人工檢查輸出是否符合預期。

基本用法：

python3 scripts/add_testcase.py \
  --kind Issue \
  --number 1234 \
  --brief-description taiwan_regional_phrase \
  --input "这个软件里有一套软体动物的数据库"

腳本預設會先執行 Bazel build，然後使用 bazel-bin/src/tools/command_line 與 建置出的詞典生成結果。測試案例 ID 會組成類似 BYVoid_OpenCC_Issue_1234_taiwan_regional_phrase 的格式。

常用參數：

  • --kind：來源類型，使用 Issue 或 PR
  • --number：issue 或 PR 編號
  • --brief-description：英文簡短描述，會作為測試案例 ID 的後綴
  • --input：測試輸入文字
  • --dry-run：只輸出將生成的 JSON，不寫入檔案
  • --replace：若同 ID 測試案例已存在，覆蓋原案例
  • --no-build：跳過 Bazel build，直接使用既有 build artifacts
  • --opencc、--config-dir、--dict-dir、--testcases：指定自訂執行檔、配置目錄、 詞典目錄或測試案例檔案

例如先預覽生成內容：

python3 scripts/add_testcase.py \
  --kind PR \
  --number 5678 \
  --brief-description hk_variant_phrase \
  --input "测试文字" \
  --dry-run

此腳本目前生成以下配置的結果：s2t、s2tw、s2twp、s2hk、t2s、 t2tw、t2hk、tw2s、tw2sp、tw2t、hk2s、hk2t。若需要測試 jp2t、t2jp，請手動在 expected 中加入對應結果。

可用的轉換配置

  • s2t - 簡體到 OpenCC 標準繁體
  • s2tw - 簡體到臺灣正體
  • s2twp - 簡體到臺灣正體（含地域用詞轉換）
  • s2hk - 簡體到香港繁體
  • tw2s - OpenCC 標準臺灣正體到簡體
  • tw2sp - 臺灣正體到簡體（含地域用詞轉換）
  • tw2t - 臺灣正體到 OpenCC 標準繁體
  • hk2s - 香港繁體到簡體
  • hk2t - 香港繁體到臺灣正體
  • t2s - OpenCC 標準繁體到簡體
  • t2tw - OpenCC 標準繁體到臺灣正體
  • t2hk - OpenCC 標準繁體到香港繁體

下列模式目前缺少大量詞組，歡迎貢獻新詞組：

  • s2hkp - 簡體到香港繁體（含地域用詞轉換）
  • hk2sp - 香港繁體到簡體（含地域用詞轉換）

下列模式僅供探索性研究，不建議用於生產環境：

  • jp2t - 日文新字體到舊字體
  • t2jp - 日文舊字體到新字體

Golden 測試

較長文本或多配置輸出可放在 test/golden/input/ 與 test/golden/output/。更新 golden 輸出時可使用：

python3 test/golden/golden_convert_test.py --update

提交前請檢查 golden diff，確認變更符合預期。

Jieba 插件測試

opencc-jieba 是可選插件，配置位於 plugins/jieba/data/config/，測試案例位於：

  • plugins/jieba/tests/data/jieba_comparison_testcases.json
  • test/golden/ 中的 _jieba 配置輸出

修改 jieba 分詞、插件載入、或 *_jieba.json 配置時，請至少執行：

bazel test --test_output=errors //plugins/jieba/... //test/golden:golden_convert_test

npm 插件包位於 plugins/jieba/node/。若修改 npm integration，請同時安裝測試 opencc 與 opencc-jieba，確認 s2twp_jieba 等模式可由 JavaScript API 與 npm CLI 載入。

範例

{
  "id": "case_050",
  "input": "這個軟體裡有一套軟體動物的資料庫",
  "expected": {
    "tw2sp": "这个软件里有一套软体动物的数据库"
  }
}

簡轉繁轉換的特殊注意事項

當您修改簡轉繁相關詞典時，需要特別注意不同地區的轉換配置可能都會受到影響。

關聯修改

如需修改 TWPhrases.txt，需要同時修改 TWPhrasesRev.txt，反之亦然。否則測試會失敗。

TWVariantsPhrases.txt 與 TWVariantsRevPhrases.txt、HKVariantsPhrases.txt 與 HKVariantsRevPhrases.txt 則不是 TWPhrases.txt / TWPhrasesRev.txt 這種 逐條互逆的詞彙對照表。*VariantsPhrases.txt 是正向地區異體字轉換的詞組級例外， 當詞組命中時，該片段會按詞組條目轉換，不再受 TWVariants.txt 或 HKVariants.txt 的字級映射影響；*VariantsRevPhrases.txt 是反向異體字轉換的詞組級例外， 命中後同樣不再受產生的 TWVariantsRev.txt 或 HKVariantsRev.txt 的字級映射影響。 兩者有關聯，但應依各自轉換方向的需要維護，不要求一組詞反向後必須出現在另一個檔案中。

涉及的配置檔案

簡轉繁轉換主要涉及以下配置：

  1. s2t.json - 基本簡轉繁

    • 使用 STPhrases.txt 和 STCharacters.txt

  2. s2tw.json - 簡體轉臺灣正體

    • 使用 STPhrases.txt、STCharacters.txt
    • 額外使用 TWVariantsPhrases.txt、TWVariants.txt

  3. s2twp.json - 簡體轉臺灣正體（含慣用詞）

    • 使用 STPhrases.txt、STCharacters.txt
    • 額外使用 TWPhrases.txt、TWVariantsPhrases.txt、TWVariants.txt

  4. s2hk.json - 簡體轉香港繁體

    • 使用 STPhrases.txt、STCharacters.txt
    • 額外使用 HKVariantsPhrases.txt、HKVariants.txt

  5. s2hkp.json - 簡體轉香港繁體（含慣用詞）

    • 使用 STPhrases.txt、STCharacters.txt
    • 額外使用 HKPhrases.txt、HKVariantsPhrases.txt、HKVariants.txt

地區慣用詞與簡繁階段

TWPhrases.txt / HKPhrases.txt 第一欄會自動生成 STPhrases_GeneratedFromRegionalPhrases，用來降低 STPhrases.txt 的維護負擔。 s2t、s2tw、s2hk、s2twp、s2hkp 等標準簡轉繁配置會在分詞階段和第一段 簡繁轉換鏈使用這份生成詞典。分詞階段可避免簡體輸入在地區詞彙階段前被錯誤切分； 第一段轉換鏈則可把 t2s(地區詞表第一欄) 投射回地區詞表 key，避免整個詞因分詞 命中而保留為簡體。

TWPhrases.txt / HKPhrases.txt 的第一欄可能是地區詞彙轉換前的另一種繁體形式， 不一定總是 OpenCC Standard Traditional 的最佳輸出。因此，如果生成結果不應成為 普通 s2t / s2tw / s2hk 的輸出，應在 STPhrases.txt 明確加入普通簡繁需要的 條目或測試來固定預期，而不是只依賴地區詞表 key。

因此，新增臺灣或香港慣用詞時，通常只需維護 TWPhrases.txt / TWPhrasesRev.txt 或 HKPhrases.txt / HKPhrasesRev.txt。當 t2s(地區詞表第一欄) 與實際簡體 輸入不一致，或普通簡繁輸出需要不同於地區詞表第一欄時，才需要額外在 STPhrases.txt 補簡繁階段的條目。

測試建議

修改 STPhrases.txt 或 STCharacters.txt 時，建議在 testcases.json 中同時測試多個相關配置：

{
  "id": "case_example",
  "input": "简体文字",
  "expected": {
    "s2t": "繁體文字",
    "s2tw": "繁體文字",
    "s2twp": "臺灣慣用詞",
    "s2hk": "香港繁體"
  }
}

這樣可以確保您的修改在各種轉換情境下都能正確運作。

常見情況

  • 僅修改基本簡繁對應：修改 STCharacters.txt，測試至少包含 s2t
  • 修改詞組轉換：修改 STPhrases.txt，測試包含 s2t、s2tw、s2twp、s2hk
  • 臺灣特有用詞：修改 TWPhrases*.txt 或 TWVariantsPhrases.txt、TWVariants.txt，測試包含 s2tw、s2twp
  • 香港特有用詞：修改 HKVariantsPhrases.txt、HKVariants*.txt，測試包含 s2hk

提交變更

完成修改後，請確認：

  • 詞典檔案已使用 Tab 字元分隔
  • 詞典檔案已正確排序（執行 sort.py 或 sort_all.py）
  • 已新增對應的測試案例到 testcases.json
  • 修改前測試案例失敗，修改後測試通過
  • 所有相關 Bazel/CMake/npm 測試通過
  • 如修改 release packaging，已檢查相關腳本（例如 scripts/release-windows-winget.ps1、npm prebuild/package 腳本）

符合以上條件後，即可提交 Pull Request。

需要協助？

如有任何問題，歡迎：

感謝您的貢獻！