Open Chinese Convert 開放中文轉換

Introduction 介紹

Open Chinese Convert (OpenCC, 開放中文轉換) is an open source project for conversions between Traditional Chinese, Simplified Chinese and Japanese Kanji (Shinjitai). It supports character-level and phrase-level conversion, character variant handling, and regional vocabulary variants across Mainland China, Taiwan and Hong Kong. This is not a translation tool between Mandarin and Cantonese, etc.

中文簡繁轉換開源項目，支持詞彙級別的轉換、異體字轉換和地區習慣用詞轉換（中國大陸、台灣、香港）及日本新字體轉換。不提供普通話與粵語之間的轉換。

Discussion (Telegram): https://t.me/open_chinese_convert

Features 特點

• 嚴格區分「一簡對多繁」和「一簡對多異」。
• 完全兼容異體字，可以實現動態替換。
• 嚴格審校一簡對多繁詞條，原則爲「能分則不合」。
• 支持中國大陸、台灣、香港異體字和地區習慣用詞轉換，如「裏」「裡」、「鼠標」「滑鼠」。
• 詞庫和函數庫完全分離，可以自由修改、導入、擴展。

詳情參閱OpenCC 設計思想及地區詞收錄標準。

Installation 安裝

Package Managers 包管理器

• Debian
• Ubuntu
• Fedora
• Arch Linux
• macOS (Homebrew)
• WinGet
  • 使用 winget install opencc 命令可直接安裝 opencc.exe 應用程式，含 Jieba 分詞插件
• Bazel
• Node.js
  • 使用 npm install -g opencc 命令可安裝 OpenCC Node.js CLI
  • 使用 npm install -g opencc opencc-jieba 命令可同時安裝 OpenCC Node.js CLI 及 Jieba 分詞插件
• Python
  • 使用 pip install opencc 命令可安裝 Python API 及 Python CLI
• More (Repology)

Prebuilt binaries 預編譯二進位檔

• Windows (x86_64): OpenCC-1.3.2 (SHA-256)
  • This Windows release is available from WinGet. For details, see doc/windows-winget-release.md.
  • Requires Microsoft Visual C++ Redistributable for Visual Studio 2015-2026. Download the latest version from Microsoft.
• Debian/Ubuntu (amd64):
  • opencc_1.3.2_amd64.deb
  • opencc-jieba_1.3.2_amd64.deb

Usage 使用

Online 線上轉換

https://opencc.js.org/converter?config=s2t

Node.js

npm install opencc

The npm package supports Node.js >=20.17. It uses bundled Node-API prebuilds when available and falls back to a local node-gyp build when the current platform does not have a matching prebuild.

To install the npm CLI:

npm install -g opencc
opencc -c s2t.json -i input.txt -o output.txt

The npm CLI supports basic text conversion. Plugins, --inspect, and --segmentation require the native OpenCC CLI.

import { OpenCC } from 'opencc';
async function main() {
  const converter: OpenCC = new OpenCC('s2t.json');
  const result: string = await converter.convertPromise('汉字');
  console.log(result);  // 漢字
}

See demo.js and ts-demo.ts.

Python

pip install opencc (Windows, Linux, macOS)

import opencc
converter = opencc.OpenCC('s2t.json')
converter.convert('汉字')  # 漢字

The Python package also installs a basic CLI:

pip install opencc
opencc -c s2t.json -i input.txt -o output.txt

The Python CLI supports basic text conversion, --include-tofu-risk-dictionaries, and --resource-zip. Diagnostic modes such as --inspect and --segmentation still require the native OpenCC CLI.

C++

 {c++}
#include "opencc.h"
 
int main() {
  const opencc::SimpleConverter converter("s2t.json");
  converter.Convert("汉字");  // 漢字
  return 0;
}

Full example with Bazel

When OpenCC is embedded in a server binary or self-contained application, the JSON config can stay small while dictionary resources are loaded from explicit resource directories:

 {c++}
#include <memory>
#include <vector>
 
#include "SimpleConverter.hpp"
 
int main() {
  auto resources = std::make_shared<opencc::FilesystemResourceProvider>(
      std::vector<std::string>{
          "/opt/my-app/opencc",
          "/opt/my-app/plugins/opencc-jieba",
          "/usr/share/opencc",
      });
  const opencc::SimpleConverter converter("s2t.json", resources);
  converter.Convert("汉字");
  return 0;
}

FilesystemResourceProvider searches directories in order. Existing SimpleConverter("s2t.json") and CLI behavior continue to use the config file location, current directory, explicit paths, and installed OpenCC data directory as before.

C

#include "opencc.h"
 
int main() {
  opencc_t opencc = opencc_open("s2t.json");
  const char* input = "汉字";
  char* converted = opencc_convert_utf8(opencc, input, strlen(input));  // 漢字
  opencc_convert_utf8_free(converted);
  opencc_close(opencc);
  return 0;
}

Full Document 完整文檔

Command Line

Unless otherwise noted, this section describes the native OpenCC CLI built from the C++ toolchain. The Python and npm CLIs support basic file/stdin conversion only, plus --include-tofu-risk-dictionaries; the Python CLI also supports --resource-zip.

• opencc --help
• opencc_dict --help

Segmentation and Inspection Modes

OpenCC CLI supports two diagnostic modes that output JSON instead of converted text:

**--segmentation** — Output segmentation result only (no conversion):

echo "他只看了几行日志，就一叶知秋，猜到整个系统是数据库连接池出了问题" | opencc -c s2twp.json --segmentation
# {"input":"他只看了几行日志，就一叶知秋，猜到整个系统是数据库连接池出了问题","segments":["他","只看","了几行","日志","，就","一叶知秋","，猜到","整个","系统","是","数据库","连接池","出了","问题"]}

**--inspect** — Output full inspection result (segmentation + per-stage conversion + final output):

echo "他只看了几行日志，就一叶知秋，猜到整个系统是数据库连接池出了问题" | opencc -c s2twp.json --inspect
# {"input":"他只看了几行日志，就一叶知秋，猜到整个系统是数据库连接池出了问题","segments":["他","只看","了几行","日志","，就","一叶知秋","，猜到","整个","系统","是","数据库","连接池","出了","问题"],"stages":[{"index":1,"segments":["他","只看","了幾行","日誌","，就","一葉知秋","，猜到","整個","系統","是","數據庫","連接池","出了","問題"]},{"index":2,"segments":["他","只看","了幾行","日誌","，就","一葉知秋","，猜到","整個","系統","是","資料庫","連線池","出了","問題"]},{"index":3,"segments":["他","只看","了幾行","日誌","，就","一葉知秋","，猜到","整個","系統","是","資料庫","連線池","出了","問題"]}],"output":"他只看了幾行日誌，就一葉知秋，猜到整個系統是資料庫連線池出了問題"}
 
# Pretty-print with jq:
echo "他只看了几行日志，就一叶知秋，猜到整个系统是数据库连接池出了问题" | opencc -c s2twp.json --inspect | jq .

These modes are useful for diagnosing conversion issues:

1. Use --segmentation to verify that the input is segmented as expected.
2. Use --inspect to see which conversion stage produces an unexpected result.

Rules:

• --segmentation and --inspect are mutually exclusive.

Official / Recommended Ports

The following ports are maintained within the OpenCC ecosystem and are generally up to date with current configuration and dictionary data.

• Data package: opencc-data
• Pure JavaScript: opencc-js
  • See links-E7%9BB8E9%97%9CE9%8F%88E6%8EA5 "notes about different OpenCC NPM packages" below.
• WebAssembly: opencc-wasm (website)
• Pure Python: opencc-py (pre-release)

Other Ports (Unofficial)

These ports are community-maintained and may not always track upstream updates.

• Swift (iOS): SwiftyOpenCC
• iOSOpenCC (pod): iOSOpenCC
• Java: opencc4j
• Android: android-opencc
• PHP: opencc4php
• WebAssembly: wasm-opencc
• Browser Extension: opencc-extension
• Go (Pure): OpenCC for Go
• Dart (native-assets): opencc-dart

Configurations 配置文件

預設配置文件

• s2t.json Simplified Chinese to Traditional Chinese (OpenCC Standard) / 簡體 到 OpenCC 標準繁體
• t2s.json Traditional Chinese (OpenCC Standard) to Simplified Chinese / OpenCC 標準繁體 到 簡體
• s2tw.json Simplified Chinese to Traditional Chinese (Taiwan Standard) / 簡體 到 台灣正體
• tw2s.json Traditional Chinese (Taiwan Standard) to Simplified Chinese / 台灣正體 到 簡體
• s2hk.json Simplified Chinese to Traditional Chinese (Hong Kong variant) / 簡體 到 香港繁體
• hk2s.json Traditional Chinese (Hong Kong variant) to Simplified Chinese / 香港繁體 到 簡體
• s2twp.json Simplified Chinese to Traditional Chinese (Taiwan Standard, with Taiwan Phrases) / 簡體 到 台灣正體（含台灣常用詞彙）
• tw2sp.json Traditional Chinese (Taiwan Standard) to Simplified Chinese (Mainland China Phrases) / 台灣正體 到 簡體（含中國大陸常用詞彙）
• t2tw.json Traditional Chinese (OpenCC Standard) to Traditional Chinese (Taiwan Standard) / OpenCC 標準繁體 到 台灣正體
• tw2t.json Traditional Chinese (Taiwan Standard) to Traditional Chinese (OpenCC Standard) / 台灣正體 到 OpenCC 標準繁體
• t2hk.json Traditional Chinese (OpenCC Standard) to Traditional Chinese (Hong Kong variant) / OpenCC 標準繁體 到 香港繁體
• hk2t.json Traditional Chinese (Hong Kong variant) to Traditional Chinese (OpenCC Standard) / 香港繁體 到 OpenCC 標準繁體

下列配置文件仍在開發中，歡迎貢獻新詞組：

• s2hkp.json Simplified Chinese to Traditional Chinese (Hong Kong variant, with Hong Kong Phrases) / 簡體 到 香港繁體（香港常用詞彙）
• hk2sp.json Traditional Chinese (Hong Kong variant) to Simplified Chinese (Mainland China Phrases) / 香港繁體 到 簡體（含中國大陸常用詞彙）

下列配置文件僅供探索性研究，不建議用於生產環境：

• t2jp.json Old Japanese Kanji (Kyūjitai) to New Japanese Kanji (Shinjitai) / 日文舊字體 到 日文新字體
• jp2t.json New Japanese Kanji (Shinjitai) to Old Japanese Kanji (Kyūjitai) / 日文新字體 到 **日文舊字體**，並將少量日文詞組轉換爲對應中文

指定配置文件

通过环境变量OPENCC_DATA_DIR加载指定路径下的配置文件

OPENCC_DATA_DIR=/path/to/your/config/dir opencc --help

內聯字典（inline dictionary）

配置檔中的字典可使用 type: "inline"，直接在 JSON 裡定義小型自訂詞彙， 不必修改外部字典檔。例如在 group.dicts 最前面加入覆寫規則：

{
  "conversion_chain": [
    {
      "dict": {
        "type": "group",
        "dicts": [
          {
            "type": "inline",
            "entries": {
              "麦旋风": "冰炫風",
              "服务器": "伺服器"
            }
          },
          {
            "type": "ocd2",
            "file": "STPhrases.ocd2"
          },
          {
            "type": "ocd2",
            "file": "STCharacters.ocd2"
          }
        ]
      }
    }
  ]
}

規則與限制：

• entries 必須是 JSON 物件。
• entries 的 key/value 必須是非空字串。
• 重複 key 不受支援；如包含，載入會直接失敗（拋出錯誤）。
• key/value 會按解析結果原樣使用，不做 trim、大小寫折疊或 Unicode normalization。
• 內聯字典與普通字典行為一致，優先級由 group.dicts 的順序決定。
• 內聯字典輸出仍會繼續經過後續 conversion_chain 步驟，不提供鎖定最終輸出。

備註：OpenCC 1.3.2+ 解析器支援有限 JSONC 語法（//、/* */ 註解與尾逗號）。 若需跨實作相容，建議使用嚴格 JSON，不依賴 JSONC 擴充。

更多完整示例可見 examples/config/。該目錄僅供學習與自訂參考，不屬於官方內建 配置列表。

Experimental Plugins 試驗性插件

OpenCC 現已支援外部 C++ 分詞插件。當前第一個插件為 opencc-jieba， 可通過 s2t_jieba.json、s2tw_jieba.json、s2hk_jieba.json、 s2twp_jieba.json、tw2sp_jieba.json 等插件配置啓用。

OpenCC now supports external C++ segmentation plugins. The first plugin is opencc-jieba, which can be enabled through plugin-backed configs such as s2t_jieba.json, s2tw_jieba.json, s2hk_jieba.json, s2twp_jieba.json, and tw2sp_jieba.json.

注意：

• 該插件機制目前仍為試驗性功能。
• jieba 插件是可選組件，預設 OpenCC 構建、Python 套件和 Node.js 套件都不要求它。
• opencc-jieba 額外依賴 cppjieba 及其配套詞典資源，這些依賴僅在構建或分發該插件時需要。
• 在下一次正式發布版本之前，插件 ABI 仍可能發生變化，不應視為穩定介面。
• 我們預計從下一次正式發布版本開始，將插件 ABI 視為穩定介面。
• Windows 下插件必須與宿主 OpenCC 二進位使用 ABI 相容的工具鏈／執行時構建；MSVC 與 MinGW 產物不支援混用。

Notes:

• The plugin mechanism is currently experimental.
• The jieba plugin is optional and is not required for the default OpenCC build, Python package, or Node.js package.
• opencc-jieba additionally depends on cppjieba and its dictionary resources. These dependencies are only needed when building or distributing the plugin itself.
• The plugin ABI may still change before the next formal OpenCC release and should not yet be treated as stable.
• We expect to treat the plugin ABI as stable starting with the next formal OpenCC release.
• On Windows, plugins must be built with an ABI-compatible toolchain/runtime as the host OpenCC binary. Mixing MSVC-built hosts with MinGW-built plugins, or the reverse, is unsupported.

Build 編譯

Build with CMake

Linux & macOS

g++ 4.6+ or clang 3.2+ is required.

make

Windows Visual Studio:

build.cmd

Build with Bazel

bazel build //:opencc

Test 測試

Linux & macOS

make test

Windows Visual Studio:

test.cmd

Test with Bazel

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

Benchmark 基準測試

make benchmark

詳情見 doc/benchmark.md 檔案。

Projects using OpenCC 使用 OpenCC 的項目

Please update if your project is using OpenCC.

• ibus-pinyin
• fcitx
• rimeime
• libgooglepinyin
• ibus-libpinyin
• alfred-chinese-converter
• GoldenDict
• China Biographical Database Project (CBDB)

License 許可協議

Apache License 2.0

Third Party Libraries 第三方庫

• darts-clone BSD License
• marisa-trie BSD License
• tclap MIT License
• rapidjson MIT License
• Google Test BSD License
• cppjieba MIT License
  • Optional dependency used by the experimental opencc-jieba plugin.
  • 試驗性 opencc-jieba 插件使用的可選依賴。

Change History 版本歷史

• NEWS
  • 另見 https://opencc.byvoid.com/news/

Links 相關連結

• Publications Using OpenCC - 近年來使用了 OpenCC 的研究論文選錄
• 現代漢語常用繁簡轉換匹配辨析表
• 關於 opencc, opencc-js 与 opencc-wasm 三个 NPM packages 區別的說明 https://github.com/nk2028/opencc-js/blob/HEAD/README-zh-TW.md#%E8%88%87-opencc-npm-package-%E7%9A%84%E5%8D%80%E5%88%A5

Contributors 貢獻者

• BYVoid
• 佛振
• Peng Huang
• LI Daobing
• Kefu Chai
• Kan-Ru Chen
• Ma Xiaojun
• Jiang Jiang
• Ruey-Cheng Chen
• Paul Meng
• Lawrence Lau
• 瑾昀
• 內木一郎
• Marguerite Su
• Brian White
• Qijiang Fan
• LEOYoon-Tsaw
• Steven Yao
• Pellaeon Lin
• stony
• steelywing
• 吕旭东
• Weng Xuetian
• Ma Tao
• Heinz Wiesinger
• J.W
• Amo Wu
• Mark Tsai
• Zhe Wang
• sgqy
• Qichuan (Sean) ZHANG
• Flandre Scarlet
• 宋辰文
• iwater
• Xpol Wan
• Weihang Lo
• Cychih
• kyleskimo
• Ryuan Choi
• Prcuvu
• Tony Able
• Xiao Liang
• Frank Lin

Please feel free to update this list if you have contributed OpenCC.