# PinyinJS

> PinyinJS converts Chinese text to pinyin in JavaScript and TypeScript. It runs in Node.js and browsers and is available as a library or CLI. The dictionary supports contextual readings, word spacing and confidence reports. The package also provides pinyin search, URL slugs, simplified and traditional character conversion, and transcription to bopomofo, Wade-Giles, Yale, Gwoyeu Romatzyh and IPA.

Each link below is the plain markdown of one page. Drop the `llms.txt` from a link for the page itself: https://pinyinjs.dev/getting-started/llms.txt is https://pinyinjs.dev/getting-started/ as HTML.

## Start here

- [Getting started](https://pinyinjs.dev/getting-started/llms.txt): Set up PinyinJS to convert Chinese characters (hanzi) to pinyin in Node.js or a browser.
- [Playground](https://pinyinjs.dev/playground/llms.txt): Try PinyinJS in the browser with live Chinese-to-pinyin conversion and simplified or traditional Chinese output.

## Guides

- [The command line](https://pinyinjs.dev/cli/llms.txt): Installing the package adds the pinyinjs command. Use it interactively, in a pipeline or with --json for structured output.
- [Converting](https://pinyinjs.dev/converting/llms.txt): convert takes a loaded dictionary and Chinese text and returns a pinyin string.
- [Orthography](https://pinyinjs.dev/orthography/llms.txt): PinyinJS applies word spacing, capitalisation and punctuation after selecting readings. For example, 我要去北京玩儿。becomes Wǒ yào qù Běijīng wánr..
- [Confidence](https://pinyinjs.dev/confidence/llms.txt): convertPieces returns pinyin one syllable at a time, with information about alternative readings.
- [HTML output](https://pinyinjs.dev/html/llms.txt): convertToHtml converts Chinese text to pinyin with one HTML element per syllable. Each element can carry a tone class and uncertainty information.
- [Segmenting](https://pinyinjs.dev/segmenting/llms.txt): segment splits Chinese text into words.
- [Matching](https://pinyinjs.dev/matching/llms.txt): match searches Chinese text using pinyin or initials and returns the matching character ranges.
- [Candidates](https://pinyinjs.dev/candidates/llms.txt): candidates finds Chinese words for a pinyin query. homophonesOf finds words with the same pronunciation as a supplied word.
- [Checking typed pinyin](https://pinyinjs.dev/checking/llms.txt): check compares typed pinyin with Chinese text and reports a verdict for each syllable.
- [Slugs](https://pinyinjs.dev/slug/llms.txt): slug converts Chinese text to a URL-safe string.
- [Dictionaries](https://pinyinjs.dev/dictionaries/llms.txt): A dictionary supplies the word readings used for Chinese-to-pinyin conversion.
- [Syllables](https://pinyinjs.dev/syllables/llms.txt): Use the syllable functions to parse, validate and format written pinyin without loading a dictionary.
- [Sandhi](https://pinyinjs.dev/sandhi/llms.txt): Tone sandhi changes a syllable's tone according to its context. PinyinJS applies it to parsed syllables, including changes across word boundaries.
- [Numbers](https://pinyinjs.dev/numerals/llms.txt): PinyinJS converts numbers to Chinese numerals and pinyin without loading a dictionary.
- [Romanisation](https://pinyinjs.dev/romanization/llms.txt): Convert pinyin syllables to and from bopomofo (注音符號), Wade-Giles, Yale, Gwoyeu Romatzyh and IPA. These functions work without a dictionary.
- [Scripts and locales](https://pinyinjs.dev/scripts-and-locales/llms.txt): Script determines which characters are written. Locale determines which pronunciation standard is used. Configure them independently.
- [Script conversion](https://pinyinjs.dev/script-conversion/llms.txt): toScript converts between simplified (简体) and traditional (繁體) Chinese.

## Reference

- [Options](https://pinyinjs.dev/options/llms.txt): Pass a ConvertOptions object as the third argument to convert, convertPieces or convertToHtml. The command line exposes the same settings as flags.
- [API](https://pinyinjs.dev/api/llms.txt): This page lists the public exports by topic. src/index.ts defines the package API.

## Optional

- [npm package](https://www.npmjs.com/package/@kensio/pinyinjs): install and version history
- [Source repository](https://github.com/KensioSoftware/pinyinjs): source, issues and the docs these pages are built from

---

# PinyinJS

Source: https://pinyinjs.dev/

PinyinJS converts Chinese characters (hanzi) to pinyin in JavaScript and
TypeScript. It runs in Node.js and browsers. Try the [playground](https://pinyinjs.dev/playground/)
or follow the setup below.

## Install

```bash
pnpm add @kensio/pinyinjs
```

Requires Node.js 22 or later, or a browser with ES modules. The package is
ESM only.

## Convert something

Load a dictionary before converting text. Dictionary data is separate from the
JavaScript bundle and loads asynchronously. Reuse the loaded dictionary across
conversions.

```ts
import { convert, loadDictionary } from "@kensio/pinyinjs";
import { fileSource } from "@kensio/pinyinjs/node";

const source = fileSource("node_modules/@kensio/pinyinjs/data");
const dictionary = await loadDictionary(source, "full");

convert(dictionary, "银行"); // "yínháng"
convert(dictionary, "行长"); // "hángzhǎng"
convert(dictionary, "我要去北京。"); // "Wǒ yào qù Běijīng."
```

In a browser, serve the package's `data/` directory and fetch it:

```ts
import { convert, fetchSource, loadDictionary } from "@kensio/pinyinjs";

const dictionary = await loadDictionary(fetchSource("/data"), "standard");
convert(dictionary, "长城"); // "Chángchéng"
```

## From the command line

The package also installs the `pinyinjs` command:

```console
$ pinyinjs convert 我要去北京。
Wǒ yào qù Běijīng.

$ pinyinjs slug 我想学中文。
wo3-xiang3-xue2-zhong1wen2

$ pinyinjs script 我们后来发现他的头发掉得很厉害。 --to zh-Hant
我們後來發現他的頭髮掉得很厲害。

$ pinyinjs explain 银行
银行  yínháng
  yín     locked
  háng    word    xíng +24.6  héng +26.6  hàng +27.6

$ pinyinjs syllable nǐhǎo
nǐhǎo  nǐ hǎo
  nǐ        n + i, tone 3         nǐ  ni3  ni³
  hǎo       h + ao, tone 3        hǎo  hao3  hao³

$ pinyinjs transcribe běijīng
běijīng     běijīng   ㄅㄟˇ ㄐㄧㄥ     pei³-ching¹ běijīng   beeijing  pei˨˩˦tɕiŋ˥
```

## Choose a guide

- [Getting started](https://pinyinjs.dev/getting-started/) covers setup and dictionary tiers.
- [Converting](https://pinyinjs.dev/converting/) explains contextual readings and custom
  pronunciations. [Options](https://pinyinjs.dev/options/) lists the available settings.
- [Orthography](https://pinyinjs.dev/orthography/) covers word spacing, capitals and punctuation.
  [Sandhi](https://pinyinjs.dev/sandhi/) explains tone changes.
- [Confidence](https://pinyinjs.dev/confidence/) shows how to inspect uncertain readings.
  [HTML output](https://pinyinjs.dev/html/) adds tone classes and readings above hanzi.
- [Matching](https://pinyinjs.dev/matching/) searches Chinese text with pinyin queries.
  [Candidates](https://pinyinjs.dev/candidates/) finds Chinese words from pinyin, and
  [checking](https://pinyinjs.dev/checking/) grades a typed transcription.
- [Slugs](https://pinyinjs.dev/slug/) creates URL slugs and search keys.
- [Script conversion](https://pinyinjs.dev/script-conversion/) converts simplified and traditional
  characters, including Taiwan and Hong Kong forms.
- [Syllables](https://pinyinjs.dev/syllables/), [numbers](https://pinyinjs.dev/numerals/) and
  [romanisation](https://pinyinjs.dev/romanization/) work without a dictionary.
- [The CLI guide](https://pinyinjs.dev/cli/) covers commands, flags and JSON output.

## Licence

The code is licensed under Apache-2.0. The compiled dictionaries in `data/`
include CC-CEDICT data and carry CC BY-SA 4.0 share-alike terms.