opencc-js

There are three primary OpenCC-related npm packages. Choosing the right one depends on your runtime environment (Browser vs. Node.js), implementation requirements (Pure JS vs. Native), and whether you need specific segmentation algorithms like Jieba.

Comparison Summary

The API patterns for opencc-js and opencc are incompatible.

opencc-js Pattern: Uses factory functions to return a plain converter function. Key entry points include:

• OpenCC.Converter({ from, to })
• ConverterFactory
• Locale

opencc Pattern: Uses a class-based approach. You instantiate it with new OpenCC(config, options) and call methods like convertSync, convert, or convertPromise.

Note on Configuration: If you are looking for OpenCC.fromConfig() (used in the native opencc package to build a converter from an inline configuration object), you should use the ConverterFactory or CustomConverter API in opencc-js to achieve the same custom-conversion use case.

To reduce bundle size (Tree Shaking), avoid importing the full opencc-js package. Instead, import from /core and /preset separately.

Recommended Pattern:

import * as OpenCC from 'opencc-js/core'; // core logic
import * as Locale from 'opencc-js/preset'; // dictionary data

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

Optimization Tips:

1. Use ConverterFactory instead of Converter.
2. Prefer regional output dictionaries (like tw or hk) over the intermediate OpenCC standard t unless specifically required.

To reduce bundle size, use ES Modules and import only the core logic and the specific presets you need. Use ConverterFactory instead of Converter for better optimization.

import * as OpenCC from 'opencc-js/core'; // Core logic
import * as Locale from 'opencc-js/preset'; // Dictionaries

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

You can load opencc-js directly in the browser using ES modules via a self-hosted file or a CDN. For older script tag usage, use the UMD build.

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 (Recommended):

<script type="module">
  import OpenCC from 'https://cdn.jsdelivr.net/npm/opencc-js@1.4.2/dist/esm/full.js';
  const converter = OpenCC.Converter({ from: 'cn', to: 'tw' });
  console.log(converter('汉语')); // 漢語
</script>

UMD build (for standard <script> tags):

<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.4.2/dist/umd/full.js"></script>

You can import OpenCC using either ES modules or CommonJS depending on your environment.

ES modules:

import OpenCC from 'opencc-js';

CommonJS:

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

To use opencc-js in a Node.js environment or with a modern bundler (like Webpack, Vite, or Rollup), install it via npm.

ES Modules:

import OpenCC from 'opencc-js';

CommonJS:

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

npm install opencc-js

Install opencc-js via npm for use in Node.js or with a bundler.

npm install opencc-js

In opencc-js, conversion processes are defined by a chain of stages.

• Stages: The outer array in a conversion configuration represents the sequence of stages in the conversion chain.
• Dictionary Groups: The inner array represents a group of dictionaries used within a single stage.
• Priority: Within a dictionary group, dictionaries listed earlier have higher priority. If multiple dictionaries in the same group contain overlapping entries, the earlier ones are applied first.