opencc-sys 0.4.3+1.3.1

OpenCC bindings for Rust
Documentation
# OpenCC 設計思想

OpenCC 默認的簡體到繁體轉換模式為 `s2t`。此模式的目標不是轉換為任何一個特定國家或地區實際使用的繁體中文,而是轉換為一種內部使用的中間詞彙標準層(intermediate lexical canonical form),稱為 **OpenCC 標準繁體**。

## 什麼是 OpenCC 標準繁體

OpenCC 標準繁體不是現實世界中任何一套完整的書寫規範,也不是香港、臺灣或其他地區的實際用字習慣。

OpenCC 標準繁體參考了《康熙字典》等各種歷史用法。它的設計目標是:

* 優先選擇語義區分能力較強、歧義較少的形式;
* 儘可能保留後續地區轉換所需的信息;
* 作為進一步轉換為香港標準、臺灣標準等模式的中間表示。

例如:

* `` 在 OpenCC 標準繁體中通常轉換為 ``* 在臺灣模式中通常保持為 ``* 在香港模式中則可能進一步轉換為 ``
這是因為 OpenCC 長期參考不同地區的辭書與官方標準,以決定特定模式下更適合使用哪種字形或詞形。例如:

* 簡體模式(`s`)參考中國大陸《通用規範漢字表》;
* 香港繁體模式(`t2hk` / `s2hk`)長期參考香港教育局《香港小學學習字詞表》等公開資料;
* 臺灣正體模式(`t2tw` / `s2tw` / `s2twp`)長期參考台灣教育部《重編國語辭典修訂本》等公開辭書。

這些標準與辭書是 OpenCC 進行工程判斷時的重要依據,但 OpenCC 本身是一個轉換工具,而不是照搬某一國家或地區標準的實作。具體條目的取捨仍需同時考慮轉換準確性、歧義風險、資料維護成本,以及既有使用者對轉換結果的兼容性預期。

實際使用習慣與官方標準之間可能存在差異,OpenCC 並不試圖覆蓋所有實際寫法。

### 為什麼使用「中間標準層」

若直接為每一對語言/地區變體建立獨立轉換規則,複雜度將隨模式數量平方增長。

假設存在:

* 簡體中文(中國)
* 簡體中文(新、馬)
* 香港繁體
* 香港繁體(含慣用詞轉換)
* 臺灣繁體
* 臺灣繁體(含慣用詞轉換)

若採用兩兩單獨轉換,需要維護 O(n²) 組規則。

採用中間標準層後,可將流程拆分為:

```
地區標準簡體 → OpenCC 標準繁體 → 地區標準繁體
```

從而將規則維護成本降低為 O(n)。

例如概念上:

* `s2tw``s2t` + `t2tw`
* `s2twp``s2t` + `t2tw` + 慣用詞轉換
* `s2hk``s2t` + `t2hk`

其他模式亦可類推。

這裡的「≈」表示概念上的組合關係;實際配置文件與詞典組織方式可能有所不同。

## OpenCC 的轉換粒度

OpenCC 的轉換主要發生在:

* 單字層級;
* 詞彙上下文中的字詞選擇。

OpenCC 不進行:

* 深層語義分析;
* 整句改寫;
* 習慣用語轉寫(除 `s2twp``tw2sp` 模式外)。

例如:

* s2tw 不會主動將整個詞組改寫為臺灣慣用語;
* s2twp 才會在 s2tw 基礎上增加慣用語詞典。

## 繁簡字詞對照表的收錄原則

繁簡字詞對照表不是規則推導表。新增或調整條目時,應優先依據可查證的語料、辭書、官方標準或既有約定俗成寫法,而不是僅憑部件類推或理論上可能存在的異體關係。

收錄時應遵循以下原則:

* 必須有足夠依據證明該寫法實際存在,且不是極少數個例;
* 必須符合對應模式的標準層定位,例如 `STCharacters.txt` 處理的是「簡體」到「OpenCC 標準繁體」,地區異體應交由相應地區變體表處理;
* 詞組通常只收錄最常用、最符合目標模式的寫法;單字在確有多個常用候選時,可以收錄多個候選;
* 不應收錄會引入高風險歧義、降低候選質量,或在人工選詞場景中造成大量低價值候選的條目;
* 不應僅因某個字形可以由部件類推、Unicode 關聯、或歷史異體關係解釋為繁簡關係,就自動加入轉換表;
* 對既有轉換結果有影響的改動應從嚴處理,優先保證現有轉換的穩定性。

實務上,OpenCC 支援的字元多數位於 BMP 與 CJK Extension A,因為這些區段已覆蓋現代文本中的絕大多數用字。超出這些區段的字元通常不主動收錄,除非能提出明確的實際使用證據。

換言之,OpenCC 可以在有明確依據時處理一簡對多繁、一繁對多簡,或多個常用異體候選;但不以窮盡所有理論上可能的字形為目標。若某個候選主要屬於臺灣、香港、日本新字體或其他特定地區/系統,應放入相應模式或另建轉換表,而不是混入通用 `s2t` / `t2s` 字表。

## 避免過度轉換

OpenCC 的另一個重要原則是:避免過度轉換。

當某個字或詞存在歧義,而無法可靠判定語義時,OpenCC 傾向於保持原文,而不是進行高風險轉換。

例如:

* `` / ``
* 某些情況下的 `` / `` / ``
* 某些情況下的 `` / `` / ``

這種設計意味著:

* 某些本可轉換的情況可能不被轉換(較低 recall);
* 但已發生的轉換通常具有較高可信度(較高 precision)。

這一策略可能導致部分使用者認為「轉換不完整」,但其目的在於降低錯誤轉換的概率,避免因誤判語義而產生更嚴重的錯誤結果。

## 轉換不保證可逆

`t2s` 可視為 `s2t` 的逆方向操作,但不保證:

```
t2s(s2t(x)) == x
```

其他模式同理。

原因包括:

* 多個來源形式可能被歸一到同一 OpenCC 標準形式;
* 某些轉換會丟失來源信息;
* 地區標準轉換本身可能進一步合併形式。

例如:

```
簡體 → OpenCC 標準繁體 → 地區繁體
```

在中間步驟中,原始信息可能已不可恢復。

## 歷史討論

關於 OpenCC 標準繁體、演算法,與相關轉換原則,曾在多個 issue 與 pull request 中反覆討論,例如:
- #1038
- #475
- #434

本文檔用於統一說明設計原則,以便後續參考。