# OpenCC for Node.js

OpenCC provides high quality conversion between Simplified Chinese,
Traditional Chinese, and regional variants. This package contains the official
Node.js bindings for the OpenCC native library.

## Installation

```bash
npm install opencc
```

The package requires Node.js `>=20.17`.

OpenCC ships native bindings. When a matching prebuilt binary is available,
installation uses it automatically. Otherwise npm builds the native addon from
source, which requires a working C++ toolchain and Python supported by
`node-gyp`.

## Basic Usage

ES modules:

```js
import OpenCC from 'opencc';

const converter = new OpenCC('s2t.json');
console.log(converter.convertSync('汉字'));
```

Promise API:

```js
import OpenCC from 'opencc';

const converter = new OpenCC('s2tw.json');
console.log(await converter.convertPromise('鼠标和软件'));
```

Named import:

```js
import { OpenCC } from 'opencc';

const converter = new OpenCC('t2s.json');
console.log(converter.convertSync('漢字'));
```

CommonJS is still supported for older projects:

```js
const { OpenCC } = require('opencc');

const converter = new OpenCC('s2t.json');
console.log(converter.convertSync('汉字'));
```

Callback API:

```js
import OpenCC from 'opencc';

const converter = new OpenCC('t2s.json');

converter.convert('漢字', (err, text) => {
  if (err) throw err;
  console.log(text);
});
```

TypeScript type declarations are included.

## API

### `new OpenCC(config?, options?)`

Creates a converter. If `config` is omitted, OpenCC uses `s2t.json`.

`config` can be one of the built-in configuration file names, such as
`s2t.json`, an absolute path to a custom OpenCC configuration file, or an
OpenCC configuration object.

`options.includeTofuRiskDictionaries` controls whether dictionaries marked as
possibly outputting tofu are loaded. Here, tofu means Chinese characters that
cannot be displayed and may render as missing-glyph boxes. It defaults to
`true` for JavaScript API compatibility.

`options.configDirectory` sets the base directory used to resolve relative
dictionary paths in inline configuration objects. It defaults to the package's
bundled OpenCC assets directory.

### `OpenCC.fromConfig(config, options?)`

Creates a converter from an OpenCC configuration object. This is equivalent to
passing the object to `new OpenCC(config, options)`.

### `converter.convertSync(input)`

Converts text synchronously and returns the converted string.

### `converter.convert(input, callback)`

Converts text asynchronously.

The callback receives `(err, convertedText)`.

### `converter.convertPromise(input)`

Converts text asynchronously and returns a `Promise<string>`.

### `OpenCC.version`

The version string of the bundled OpenCC native library.

### `OpenCC.generateDict(inputFileName, outputFileName, formatFrom, formatTo)`

Generates a dictionary file from another dictionary format.

For example, convert a text dictionary to OpenCC's binary `ocd2` format:

```js
import { OpenCC } from 'opencc';

OpenCC.generateDict('my-dict.txt', 'my-dict.ocd2', 'text', 'ocd2');
```

## Command Line

Install OpenCC globally to use the npm command line tool:

```bash
npm install -g opencc
```

The package installs an `opencc` command:

```bash
opencc -c s2t.json -i input.txt -o output.txt
```

It can also read from stdin and write to stdout:

```bash
echo '汉字' | opencc -c s2t.json
```

Options:

```text
-c, --config <file>  Configuration file. Defaults to s2t.json.
-i, --input <file>   Read original text from <file>. Defaults to stdin.
-o, --output <file>  Write converted text to <file>. Defaults to stdout.
--include-tofu-risk-dictionaries
                     Include dictionaries that may output tofu: Chinese
                     characters rendered as missing-glyph boxes.
-v, --version        Print OpenCC version.
-h, --help           Print help.
```

The npm CLI skips dictionaries marked as possibly outputting tofu by default.
Here, tofu means Chinese characters that cannot be displayed and may render as
missing-glyph boxes. Use `--include-tofu-risk-dictionaries` to load them. The
npm CLI supports conversion only. Use the native OpenCC command line tool for
inspection, segmentation output, custom resource search paths, or other
advanced CLI features.

## Built-in Configurations

| Configuration | Conversion |
| --- | --- |
| `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 標準繁體 |
| `t2jp.json` | Traditional Chinese Characters (Kyūjitai) to New Japanese Kanji (Shinjitai) / OpenCC 標準繁體（日文舊字體）到日文新字體 |
| `jp2t.json` | New Japanese Kanji (Shinjitai) to Traditional Chinese Characters (Kyūjitai) / 日文新字體到 OpenCC 標準繁體（日文舊字體） |

## Custom Configurations

Pass a path to a custom OpenCC configuration JSON file:

```js
import OpenCC from 'opencc';

const converter = new OpenCC('/absolute/path/to/custom.json');
console.log(converter.convertSync('汉字'));
```

Relative config paths are resolved from the current working directory by the
CLI. In the JavaScript API, relative config names are resolved from the package
assets directory, so custom configs should be passed as absolute paths.

You can also pass an OpenCC configuration object directly:

```js
import OpenCC from 'opencc';

const converter = OpenCC.fromConfig({
  name: 'Custom Inline Config',
  segmentation: {
    type: 'mmseg',
    dict: { type: 'inline', entries: { '鼠标': '鼠标' } },
  },
  conversion_chain: [{
    dict: { type: 'inline', entries: { '鼠标': '滑鼠' } },
  }],
});

console.log(converter.convertSync('鼠标坏了'));
```

When an inline configuration references relative dictionary files, pass
`configDirectory`:

```js
const converter = OpenCC.fromConfig(config, {
  configDirectory: '/absolute/path/to/opencc-resources',
});
```

Custom dictionaries can be generated with `OpenCC.generateDict()` or with the
native `opencc_dict` tool from the full OpenCC distribution.

## Optional Jieba Configurations

Some OpenCC configurations use jieba segmentation. Install the optional
`opencc-jieba` package to make jieba-backed configs available:

```bash
npm install opencc opencc-jieba
```

When `opencc-jieba` is installed, the JavaScript API and npm `opencc` CLI can
load its configs automatically:

Available plugin-backed configs include `s2t_jieba.json`,
`s2tw_jieba.json`, `s2hk_jieba.json`, `s2twp_jieba.json`, and
`tw2sp_jieba.json`.

```js
import OpenCC from 'opencc';

const converter = new OpenCC('s2twp_jieba');
console.log(converter.convertSync('软件鼠标'));
```

The npm CLI also accepts the same config names for text conversion:

```bash
opencc -c s2twp_jieba
```

Use the native OpenCC CLI for diagnostic modes such as `--inspect` and
`--segmentation`.

## Related npm Packages

The [`opencc`](https://www.npmjs.com/package/opencc) npm package is the
Node.js native binding for the official OpenCC C++ project. It is intended for
Node.js, depends on native or prebuilt binaries, and follows the official
OpenCC engine. It can use extended segmentation algorithms such as Jieba when
supported by the official OpenCC configuration and runtime.

The [`opencc-js`](https://www.npmjs.com/package/opencc-js) npm package is a
pure JavaScript implementation for browsers and Node.js. It bundles dictionary
data generated from `opencc-data`, so it does not require native binaries and
does not fetch dictionary text files at runtime.

`opencc-js` has aligned its conversion flow with the official OpenCC
implementation, including phrase segmentation for built-in converters, and is
tested against upstream OpenCC test cases and golden outputs. It still should
not be treated as guaranteed to produce 100% identical results for every
possible input.

`opencc-js` currently supports the built-in OpenCC mmseg-style segmentation
used by its bundled converters, but it does not support extended segmentation
algorithms such as Jieba.

The [`opencc-wasm`](https://www.npmjs.com/package/opencc-wasm) npm package is
another browser-capable implementation. It uses WebAssembly, keeps its
configuration and conversion logic aligned with the official `opencc` package,
and can support Jieba segmentation through the official OpenCC runtime.

## Development

From the repository root:

```bash
npm install
npm test
```

The `OpenCCConfig` TypeScript declarations in `opencc.d.ts`,
`opencc.d.cts`, and `opencc.d.mts` are generated from
`data/config/opencc_config.schema.json`. Regenerate them after changing the
schema:

```bash
npm run generate:node-config-types
```

To build prebuilt native addons for publishing, see
[`node/PUBLISHING.md`](./PUBLISHING.md).
