opencc-wasm


English

> 🚀 開箱即用的中文簡繁轉換程式庫 - 3 行程式碼搞定，自動從 CDN 載入設定和字典！

OpenCC（Open Chinese Convert）的 WebAssembly 移植版本，完全相容原版 API。內建官方 OpenCC C++ 核心（透過 Emscripten 編譯），以及所有官方設定檔和預先建置的 .ocd2 字典檔。

授權條款： Apache-2.0

✨ 特色功能

- 🎯 零設定 - 自動從 CDN 載入所有設定檔和字典檔
- 🔥 3 行開始 - 最簡單的 API，匯入即用
- 🌐 CDN 就緒 - 可直接從 jsDelivr/unpkg 使用，無需打包工具
- 📦 一應俱全 - 包含所有 14+ 種官方轉換類型
- ⚡ 自動快取 - 資源首次載入後自動快取
- 🔧 完全相容 - 相容 opencc-js API
- 🚫 無需原生綁定 - 純 WASM，跨平台
- 💻 通用支援 - 支援 Node.js、瀏覽器、Deno 等環境

🚀 快速開始

$3

``html

`

就是這麼簡單！ 所有設定檔和字典檔都會自動從 CDN 下載。

$3

`bash
npm install opencc-wasm
`

`javascript
import OpenCC from "opencc-wasm";

const converter = OpenCC.Converter({ config:"s2twp" });
const result = await converter("简体中文");
console.log(result); // 簡體中文
`

📖 API 參考

$3

兩種方式指定轉換：

#### 方式 1：使用 config 參數（推薦）

直接指定 OpenCC 設定檔名稱：

`javascript
// 簡體 → 繁體（台灣慣用詞）
const converter = OpenCC.Converter({ config: "s2twp" });
const result = await converter("服务器软件"); // 伺服器軟體
`

支援的設定檔：

| 設定檔 | 說明 | 範例 |
|--------|------|------|
| s2twp | 簡體 → 台灣正體（含地域用詞轉換） | 軟體 → 軟體 |
| s2twp_jieba | 簡體 → 台灣正體（jieba 分詞） | 城堡的士兵 → 城堡的士兵 |
| s2tw | 簡體 → 台灣正體 | 心里 → 心裡 |
| s2hk | 簡體 → 香港繁體 | 心里 → 心裏 |
| s2t | 簡體 → OpenCC 標準繁體 | 简体 → 簡體 |
| tw2sp | 台灣正體 → 簡體（含地域用詞轉換） | 滑鼠 → 鼠标 |
| tw2sp_jieba | 台灣正體 → 簡體（jieba 分詞） | 慰藉著 → 慰藉着 |
| tw2s | 台灣正體 → 簡體 | 軟體 → 软件 |
| tw2t | 台灣正體 → OpenCC 標準繁體 | 吃飯 → 喫飯 |
| hk2s | 香港繁體 → 簡體 | 打印機 → 打印机 |
| hk2t | 香港繁體 → OpenCC 標準繁體 | 為 → 爲 |
| t2s | OpenCC 標準繁體 → 簡體 | 繁體 → 繁体 |
| t2tw | OpenCC 標準繁體 → 台灣正體 | 牀 → 床 |
| t2hk | OpenCC 標準繁體 → 香港繁體 | 爲 → 為 |
| jp2t | 日文新字體 → 日文舊字體 | 桜花 → 櫻花 |
| t2jp | 日文舊字體 → 日文新字體 | 櫻花 → 桜花 |
| t2cngov | 繁體 → 大陸政府標準繁體 | 潮溼 → 潮湿 |
| t2cngov_keep_simp | 繁體 → 大陸政府標準繁體（保留簡體） | 简体繁體 → 简体繁體 |

#### 方式 2：使用 from/to 參數（与 opencc-js 相容）

指定來源和目標語系：

`javascript
const converter = OpenCC.Converter({ from: "cn", to: "twp" });
const result = await converter("服务器"); // 伺服器
`

語系代碼：

| 代碼 | 說明 |
|------|------|
| cn | 簡體中文（中國大陸） |
| tw | 繁體中文（台灣） |
| twp | 台灣正體（含慣用詞） |
| hk | 繁體中文（香港） |
| t | 繁體中文（通用） |
| s | 簡體中文（別名） |
| sp | 簡體（含慣用詞） |
| jp | 日文新字體 |

兩種方式功能完全相同！ 選擇您喜歡的即可。

$3

`javascript
const converter = OpenCC.ConverterFactory(
"cn", // from
"tw", // to
[ // 自訂字典
[["服务器", "伺服器"], ["文件", "檔案"]],
"網路 网络 | 檔案 文件"
]
);

const result = await converter("服务器上的文件通过网络传输");
// 輸出：伺服器上的檔案通過網路傳輸
`

$3

`javascript
const converter = OpenCC.CustomConverter([
[""", "「"],
[""", "」"],
["'", "『"],
["'", "』"],
]);

const result = converter("这是"引号"和'单引号'");
// 輸出：这是「引号」和『单引号』
`

💡 使用範例

$3

`jsx
import { useState } from 'react';
import OpenCC from 'opencc-wasm';

function App() {
const [output, setOutput] = useState('');

const handleConvert = async () => {
const converter = OpenCC.Converter({ config: "s2tw" });
setOutput(await converter("简体中文"));
};

return (


`vue



`

$3

`javascript
#!/usr/bin/env node
import OpenCC from 'opencc-wasm';

const text = process.argv[2] || "简体中文";
const converter = OpenCC.Converter({ config: "s2tw" });
console.log(await converter(text));
`

$3

`javascript
// worker.js
import OpenCC from 'opencc-wasm';

let converters = {};

self.onmessage = async (e) => {
const { config, text } = e.data;

if (!converters[config]) {
converters[config] = OpenCC.Converter({ config });
}

const result = await convertersconfig;
self.postMessage(result);
};
`

`javascript
// main.js
const worker = new Worker('worker.js', { type: 'module' });

worker.onmessage = (e) => {
console.log('結果：', e.data);
};

worker.postMessage({ config: 's2tw', text: '简体中文' });
`

🔧 最佳實務

$3

`javascript
// ✅ 好：建立一次，多次使用
const converter = OpenCC.Converter({ config: "s2tw" });

for (const text of manyTexts) {
await converter(text); // 快！
}
`

`javascript
// ❌ 避免：每次都建立新實例
for (const text of manyTexts) {
const converter = OpenCC.Converter({ config: "s2tw" }); // 慢！
await converter(text);
}
`

$3

`javascript
// 建立多個轉換器（資源自動快取）
const s2t = OpenCC.Converter({ config: "s2t" });
const s2tw = OpenCC.Converter({ config: "s2tw" });
const t2s = OpenCC.Converter({ config: "t2s" });

// 獨立使用
console.log(await s2t("简体")); // 簡體
console.log(await s2tw("软件")); // 軟體
console.log(await t2s("繁體")); // 繁体
`

$3

`typescript
import OpenCC from 'opencc-wasm';

type ConfigName = 's2t' | 's2tw' | 's2twp' | 's2twp_jieba' | 't2s' | 'tw2sp_jieba';

async function convert(config: ConfigName, text: string): Promise {
const converter = OpenCC.Converter({ config });
return await converter(text);
}

const result = await convert('s2tw', '简体中文');
`

🏗️ 建置

專案使用兩階段建置流程：

$3

`bash
./build.sh
`

編譯 OpenCC + marisa-trie 成 WASM，輸出至 build/：
- build/opencc-wasm.esm.js - ESM WASM 膠合程式
- build/opencc-wasm.cjs - CJS WASM 膠合程式
- build/opencc-wasm.wasm - WASM 二進位檔

$3

`bash
node scripts/build-api.js
`

產生可發佈的發行版至 dist/：
- 複製 WASM 檔案至 dist/esm/ 和 dist/cjs/
- 轉換原始碼至生產環境路徑
- 複製資料檔至 dist/data/

$3

`bash
npm run build
`

自動執行兩個階段。

🧪 測試

`bash
npm test
`

執行上游 OpenCC 測試案例來驗證 WASM 建置。

📁 專案結構

`
wasm-lib/
├── build/ ← 中間產物（gitignored）
├── dist/ ← 可發佈版本（已提交）
│ ├── esm/
│ │ ├── index.js
│ │ ├── opencc-wasm.js
│ │ └── opencc-wasm.wasm
│ ├── cjs/
│ │ ├── index.cjs
│ │ ├── opencc-wasm.cjs
│ │ └── opencc-wasm.wasm
│ └── data/ ← OpenCC 設定檔 + 字典
├── index.js ← 原始碼 API
├── index.d.ts ← TypeScript 型別定義
└── scripts/
└── build-api.js ← 建置腳本
`

❓ 常見問題

Q：設定檔和字典會自動載入嗎？還是需要我手動下載？

A：自動載入！高階 API（OpenCC.Converter()）會自動從 CDN 下載所有需要的檔案。

Q：每次轉換都會重新下載嗎？

A：不會！資源在首次載入後會快取起來。

Q：可以離線使用嗎？

A：可以！透過 npm 安裝時，所有資源都已包含在套件中。瀏覽器環境可使用 Service Worker 實現離線快取。

Q：應該用 config 還是 from/to 參數？

A：兩者功能完全相同。如果您熟悉 OpenCC 設定檔名稱，用 config；若偏好語系導向的方式，用 from/to。

Q：為什麼第一次轉換比較慢？

A：首次載入需要下載設定檔和字典檔（約 1-2MB）。後續轉換會很快（已快取）。

📝 注意事項

- 使用持久的 OpenCC 控制代碼避免重複載入設定
- 字典儲存在虛擬檔案系統的 /data/dict/ 中
- Jieba 資產儲存在 /data/jieba_dict/（詞典、hmm_model、user dict、idf、stop_words）
- 記憶體按需成長（ALLOW_MEMORY_GROWTH=1）
- 效能：專注於精確度和與官方 OpenCC 的相容性。原始吞吐量可能比純 JavaScript 實作慢，但保證完整的 OpenCC 行為。

📜 變更歷史

$3

- 新增 Jieba 分詞支援（cppjieba）以改善詞組切分效果
- 新增轉換設定：s2twp_jieba、tw2sp_jieba
- wasm 發行包內含 Jieba 詞典與模型檔
- 新增 Jieba 對照測試與使用說明

$3

- 與上游分支狀態對齊後的重新發布
- 少量詞條修正與小型 bugfixes

$3

- 小型 bugfixes 與細節修正

$3

- 修正 WASM 載入子目錄詞典（例如 cngov）時的目錄建立
- 資產刷新腳本可正確處理巢狀 .ocd2 與 config JSON 複製

$3

新增：
- Converter() 新增 config 參數，可直接使用 OpenCC 設定檔名稱
- 新增中國政府規範字轉換：t2cngov、t2cngov_keep_simp
- 新增示範頁與回歸測試，涵蓋新設定

修正：
- 修復 s2twp 重複字元問題（issue #950）
- 修正 tw2sp 方程式 轉換錯誤並同步字典
- 補齊 wasm-lib 發行包中的 cngov 設定與字典

$3

🚨 重大變更：新的發行版佈局

.wasm 檔案已移至與膠合程式同目錄：
- dist/esm/opencc-wasm.wasm（舊：dist/opencc-wasm.esm.wasm）
- dist/cjs/opencc-wasm.wasm（舊：dist/opencc-wasm.cjs.wasm）

新增：
- CDN 支援，可直接在瀏覽器中使用
- 完整測試套件
- 自動載入設定檔和字典檔

$3

- 提供兩種 wasm 檔名以相容性

$3

- 從 OpenCC commit 36c7cbbc 重新建置
- 新的 dist 佈局，ESM/CJS 分離
- 測試改用 node:test` 重寫

---

用 ❤️ 為中文 NLP 社群打造