opencc-js

繁體版 - 简体版

The Pure JavaScript version of Open Chinese Convert (OpenCC)

opencc-js is a pure JavaScript implementation of OpenCC for both browsers and Node.js. It bundles dictionary data generated from opencc-data at build time, and no native binary is required.

The conversion pipeline aligns with the official OpenCC implementation, including phrase-level segmentation for the built-in converters, verified against upstream OpenCC test cases and golden outputs. Exact parity with the official OpenCC output is not guaranteed for all inputs.

opencc-js supports the OpenCC mmseg-style segmentation used by the built-in converters, but does not support extended segmenters such as jieba.

Note: For a comparison with the opencc and opencc-wasm packages, see below.

Data

Dictionary data is generated from opencc-data at build time and bundled in the published package. Browser usage does not fetch extra dictionary text files at runtime.

To avoid producing tofu boxes for glyphs that are often missing from browser and system fonts, opencc-js does not bundle OpenCC's TSCharactersExt tofu-risk mappings. A small number of rare Traditional-to-Simplified extension-character conversions may therefore intentionally differ from the upstream OpenCC test data.

Usage

Choose the installation method that matches your environment.

Important: Version 1.4.1 syncs with opencc-data 1.4.1 and refreshes the generated dictionary data.

Install opencc-js for Node.js or a bundler

npm install opencc-js

ES modules:

import OpenCC from 'opencc-js';

CommonJS:

const OpenCC = require('opencc-js');

Use opencc-js in a browser

Self-hosted ES module:

<script type="module">
  import OpenCC from './dist/esm/full.js';

  const converter = OpenCC.Converter({ from: 'cn', to: 'tw' });
  console.log(converter('汉语')); // 漢語
</script>

CDN ES module:

<script type="module">
  // Use the latest stable version from https://www.npmjs.com/package/opencc-js, or pin 1.4.1 explicitly
  import OpenCC from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/esm/full.js';

  const converter = OpenCC.Converter({ from: 'cn', to: 'tw' });
  console.log(converter('汉语')); // 漢語
</script>

UMD build for plain script tags:

<!-- Use the latest stable version from https://www.npmjs.com/package/opencc-js, or pin 1.4.1 explicitly -->

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/full.js"></script>

Basic usage

// Convert Traditional Chinese (Hong Kong) to Simplified Chinese (Mainland China)
const converter = OpenCC.Converter({ from: 'hk', to: 'cn' });
console.log(converter('漢語')); // output: 汉语

Custom Converter

const converter = OpenCC.CustomConverter([
  ['香蕉', 'banana'],
  ['蘋果', 'apple'],
  ['梨', 'pear'],
]);
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear

Or using space and vertical bar as delimiter.

const converter = OpenCC.CustomConverter('香蕉 banana|蘋果 apple|梨 pear');
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear

Add words

• Use low-level function ConverterFactory to create converter.
• Get dictionary from the property Locale.

const customDict = [
  ['“', '「'],
  ['”', '」'],
  ['‘', '『'],
  ['’', '』'],
];
const converter = OpenCC.ConverterFactory(
  OpenCC.Locale.from.cn,                   // Simplified Chinese (Mainland China) => OpenCC standard
  OpenCC.Locale.to.tw.concat([customDict]) // OpenCC standard => Traditional Chinese (Taiwan) with custom words
);
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」

This will get the same result with an extra conversion.

const customDict = [
  ['“', '「'],
  ['”', '」'],
  ['‘', '『'],
  ['’', '』'],
];
const converter = OpenCC.ConverterFactory(
  OpenCC.Locale.from.cn, // Simplified Chinese (Mainland China) => OpenCC standard
  OpenCC.Locale.to.tw,   // OpenCC standard => Traditional Chinese (Taiwan)
  [customDict]           // Traditional Chinese (Taiwan) => custom words
);
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」

DOM operations

HTML attribute lang='*' defines the targets.

<span lang="zh-HK">漢語</span>

// Set Chinese convert from Traditional (Hong Kong) to Simplified (Mainland China)
const converter = OpenCC.Converter({ from: 'hk', to: 'cn' });
// Set the conversion starting point to the root node, i.e. convert the whole page
const rootNode = document.documentElement;
// Convert all elements with attributes lang='zh-HK'. Change attribute value to lang='zh-CN'
const HTMLConvertHandler = OpenCC.HTMLConverter(converter, rootNode, 'zh-HK', 'zh-CN');
HTMLConvertHandler.convert(); // Convert  -> 汉语
HTMLConvertHandler.restore(); // Restore  -> 漢語

API

• .Converter({}): declare the converter's direction via locales.
  • default: { from: 'tw', to: 'cn' }
  • syntax : { from: locale1, to: locale2 }
• locales: letter codes defining a writing locale and, occasionally, its idiomatic habits.
  • cn: Simplified Chinese (Mainland China)
  • tw: Traditional Chinese (Taiwan)
    • twp: with phrase conversion (ex: 自行車 -> 腳踏車）
  • hk: Traditional Chinese (Hong Kong)
    • hkp: with Hong Kong phrase conversion (ex: 鼠標 -> 滑鼠)
  • jp: Japanese Shinjitai
  • t: Traditional Chinese (OpenCC standard), mainly useful as an intermediate form

Unless you specifically need the OpenCC standard Traditional Chinese intermediate form, prefer regional output such as tw, twp, hk, or hkp instead of to: 't'.

| opencc-js options | OpenCC config | Notes | |---|---|---| | { from: 'cn', to: 'tw' } | s2tw | Recommended for Simplified Chinese to Traditional Chinese (Taiwan). | | { from: 'cn', to: 'twp' } | s2twp | Recommended for Simplified Chinese to Traditional Chinese (Taiwan) with phrase conversion. | | { from: 'cn', to: 'hk' } | s2hk | Recommended for Simplified Chinese to Traditional Chinese (Hong Kong). | | { from: 'cn', to: 'hkp' } | s2hkp | Simplified Chinese to Traditional Chinese (Hong Kong) with phrase conversion. The phrase dictionary is still developing and currently small; use with care. | | { from: 't', to: 'cn' } | t2s | Recommended for generic Traditional Chinese to Simplified Chinese. | | { from: 'tw', to: 'cn' } | tw2s | Recommended for Traditional Chinese (Taiwan) to Simplified Chinese. | | { from: 'twp', to: 'cn' } | tw2sp | Recommended for Traditional Chinese (Taiwan, with phrases) to Simplified Chinese. | | { from: 'hk', to: 'cn' } | hk2s | Recommended for Traditional Chinese (Hong Kong) to Simplified Chinese. | | { from: 'hkp', to: 'cn' } | hk2sp | Traditional Chinese (Hong Kong, with phrases) to Simplified Chinese. The phrase dictionary is still developing and currently small; use with care. | | { from: 'cn', to: 't' } | s2t | Advanced: Simplified Chinese to OpenCC standard Traditional Chinese. Usually not the best end-user display locale. | | { from: 't', to: 'tw' } | t2tw | Advanced: OpenCC standard Traditional Chinese to Traditional Chinese (Taiwan). | | { from: 't', to: 'hk' } | t2hk | Advanced: OpenCC standard Traditional Chinese to Traditional Chinese (Hong Kong). | | { from: 'tw', to: 't' } | tw2t | Advanced: Traditional Chinese (Taiwan) to OpenCC standard Traditional Chinese. | | { from: 'hk', to: 't' } | hk2t | Advanced: Traditional Chinese (Hong Kong) to OpenCC standard Traditional Chinese. | | { from: 'jp', to: 't' } | jp2t | Experimental: Japanese Shinjitai to OpenCC standard Traditional Chinese. Not recommended for production use. | | { from: 't', to: 'jp' } | t2jp | Experimental: OpenCC standard Traditional Chinese to Japanese Shinjitai. Not recommended for production use. |

• .CustomConverter([]) : defines custom dictionary.
  • default: []
  • syntax : [ ['item1','replacement1'], ['item2','replacement2'], … ]
• .HTMLConverter(converter, rootNode, langAttrInitial, langAttrNew ) : uses previously defined converter() to convert all HTML elements text content from a starting root node and down, into the target locale. Also converts all attributes lang from existing langAttrInitial to langAttrNew values, and converts placeholder and aria-label attributes.
• lang attributes : html attribute defines the languages of the text content to the browser, at start (langAttrInitial) and after conversion (langAttrNew).
  • syntax convention: IETF languages codes, mainly zh-TW, zh-HK, zh-CN, zh-SG,…
• ignore-opencc : html class signaling an element and its sub-nodes will not be converted.

Bundle optimization

• Tree Shaking (ES Modules Only) may result less size of bundle file.
• Using ConverterFactory instead of Converter.
• Prefer regional output dictionaries such as tw or hk over to: 't' unless you specifically need OpenCC standard Traditional Chinese.

import * as OpenCC from 'opencc-js/core'; // primary code
import * as Locale from 'opencc-js/preset'; // dictionary

const converter = OpenCC.ConverterFactory(Locale.from.hk, Locale.to.cn);
console.log(converter('漢語'));

Differences between various opencc npm packages

There are three related npm packages for OpenCC conversion. They differ in runtime environment, implementation approach, and segmentation support.

opencc-js is a pure JavaScript implementation for browsers and Node.js. It bundles dictionary data generated from opencc-data at build time, requiring no native binaries and no runtime file fetching. Its conversion pipeline aligns with the official OpenCC implementation, including mmseg-style phrase segmentation for built-in converters, verified against upstream OpenCC test cases and golden outputs. Exact parity with the official OpenCC output is not guaranteed for all inputs. Extended segmenters such as Jieba are not supported.

opencc is the official Node.js native binding for the OpenCC C++ project. It depends on native or prebuilt binaries and follows the official OpenCC engine. Extended segmentation algorithms such as Jieba are supported when the official OpenCC configuration and runtime allow it.

opencc-js and opencc also expose different API shapes: opencc-js uses factory functions (OpenCC.Converter({ from, to }), ConverterFactory, Locale) that return a plain converter function, while opencc exposes a class (new OpenCC(config, options)) with convertSync/convert/convertPromise methods. This has been true since opencc-js predates opencc's current API, and opencc-js does not track it. In particular, opencc's OpenCC.fromConfig() entry point for building a converter from an inline OpenCC configuration object is native-opencc-specific; opencc-js covers the same custom-conversion use case with its own ConverterFactory/CustomConverter API instead.

opencc-wasm is another browser-capable implementation using WebAssembly. Its configuration and conversion logic stay aligned with the official opencc package, and it can support Jieba segmentation through the official OpenCC runtime.

| | opencc-js | opencc | opencc-wasm | |---|---|---|---| | Browser | ✅ | ❌ | ✅ | | Node.js | ✅ | ✅ | ✅ | | Implementation | Pure JavaScript | Native C++ binding | WebAssembly | | Native binary required | ❌ | ✅ | ❌ | | Dictionary source | Bundled at build time | Loaded at runtime | Loaded at runtime | | Aligned with official OpenCC | Approximately | ✅ | ✅ | | mmseg segmentation | ✅ | ✅ | ✅ | | Jieba segmentation available | ❌ | ✅ | ✅ |