opencc-py

opencc-py 是依照 Will 保哥的 C# OpenCC 實作移植的純 Python OpenCC 函式庫。核心行為保留原實作的內嵌詞庫、locale/preset、Trie 最長匹配與多階段轉換流程。

範例

請參考 examples/，內含基本轉換、不套用詞彙轉換、不同簡繁詞庫差異、自訂詞典與 HTML/XML 轉換範例。

功能

• 純 Python 3.11+，無執行階段相依套件。
• 內建 cn、hk、tw、tw2、twp、jp locale。
• 支援 full、cn2t、t2cn preset。
• 支援自訂字典與多個字典群組串接。
• Unicode code point 層級的 Trie 最長匹配。
• XML 相容 HTML 轉換與還原。
• 提供 opencc-py CLI。

安裝

pip install opencc-py-tw2

基本用法

from opencc_py import converter

convert = converter("cn", "tw2")
print(convert("汉语"))  # 漢語
print(convert.convert("默认用户界面支持数据库和网络请求。"))

Locale 與 preset

預設 opencc_py.converter(from_, to) 使用 full preset：

tw2 的「台／臺」規則：日常用語用「台」（台北、舞台、電視台），「颱」「檯」不變（颱風、櫃檯），正式名稱保留「臺」（國立臺灣大學、臺北市政府、新臺幣）。輸入寫成「台」的正式名稱也會統一成「臺」。tw2 轉回其他地區時不會把「台」改回「臺」，所以 tw → tw2 → tw 不保證能還原原文。白名單來源是 opencc-js 的 src/custom/TW2TaiProperNouns.js，字典資料是 TW2Tai／TW2TaiRev，用 opencc-js 的 tools/gen-tw2-tai.mjs 產生。

方向限定 preset：

from opencc_py import presets

cn_to_tw = presets.cn2t.converter("cn", "tw2")
tw_to_cn = presets.t2cn.converter("tw2", "cn")

自訂字典

字串格式與 C# 實作相同：每筆 來源 目標，筆與筆之間以 | 分隔；若詞條內含空白，可用 tab 分隔來源與目標。

from opencc_py import DictEntry, custom_converter

convert = custom_converter("香蕉 banana|蘋果 apple|Web 平台庫\tWeb 平台函式庫")
print(convert("香蕉 蘋果 Web 平台庫"))

convert2 = custom_converter([
    DictEntry("“", "「"),
    DictEntry("”", "」"),
])

進階組合

converter_factory() 會依序套用每個 DictGroup，等同 C# 版本先處理 from 群組，再處理 to 群組。

from opencc_py import DictEntry, DictGroup, converter_factory

first = DictGroup.from_entries([DictEntry("a", "b")])
second = DictGroup.from_entries([DictEntry("b", "c")])
convert = converter_factory(first, second)
print(convert("a"))  # c

XML 相容 HTML 轉換

此功能使用 Python 標準函式庫 xml.etree.ElementTree，適用於可被 XML parser 解析的 HTML/XML。它會轉換符合 lang 範圍內的文字、meta[name=description|keywords] 的 content、img alt、input[type=button] value，並略過 script、style 與 ignore-opencc class。

from opencc_py import HtmlConverter, converter

convert = converter("hk", "cn")
html = HtmlConverter.from_xml_string(
    convert,
    "<html lang='zh-HK'><body><p lang='zh-HK'>漢語</p></body></html>",
    "zh-HK",
    "zh-CN",
)
html.convert()
print(html.to_xml_string())
html.restore()

CLI

opencc-py input.txt cn tw2
opencc-py input.txt cn tw2 -o output.txt
opencc-py input.txt cn tw2 --in-place

-o/--output 與 -i/--in-place 不能同時使用。輸入與輸出皆使用 UTF-8。

範例

更多可執行範例請見 samples/。

開發

python -m venv .venv
source .venv/bin/activate
python -m unittest discover -s tests
python -m pip install build
python -m build

如果 C# OpenCC 原始碼與本專案位於同一個父目錄，可重新產生內嵌詞庫：

python tools/generate_dict_data.py
python -m unittest discover -s tests

發布

PyPI 發布流程請見 PUBLISHING.md。

授權

MIT

台灣詞彙品質改善

tw2 / twp 的共用詞彙規則、語境限制、測試結果與效能對照，請見 台灣詞彙品質說明。