Library / SDK
zh-lx/pinyin-pro avatar
zh-lx/pinyin-pro

pinyin-pro: Chinese to pinyin with matching and word segmentation

Converts Chinese to pinyin, with tone marks, initials, finals, multi-pronunciation characters, surname pinyin, pinyin matching and Chinese word segmentation.

4,770 stars405 forksTypeScriptMIT

At a glance

What is it?
pinyin-pro is a TypeScript library that turns Chinese characters into pinyin, with tone marks, initials, finals, multi-pronunciation characters, surname pinyin, pinyin matching and word segmentation. Its repository carries accuracy and speed scripts and lists two other pinyin libraries, pinyin and @napi-rs/pinyin, as devDependencies.
Who is it for?
pinyin-pro fits a JavaScript or TypeScript product that needs Chinese-to-pinyin conversion with tone marks, multi-pronunciation characters, surname readings, pinyin matching or word segmentation. Before you commit, run the repository's accuracy and speed scripts yourself, since the comparison against pinyin and @napi-rs/pinyin is the maintainer's own, and check that your Node version clears the stated floor of 18.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 43 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • zh-lx/pinyin-pro4,770 ★ · +44
Star history
Repository2026-09-232026-11-21
zh-lx/pinyin-pro4.7k4.8k

44 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

toneType picks the shape of the output, nothing else changes

The repository description says pinyin-pro converts Chinese to pinyin with tone marks, initials and finals, and handles multi-pronunciation characters and surname pinyin.

match() accepts zwp, zhongwenpin, or zhongwp

Pinyin matching is one of the features the repository description lists.

Convert an existing reading without re-analysing the characters

Use `convert()` when you already know the pronunciation and need a different tone format. The [conversion API](https://pinyin-pro.cn/use/convert.html) documents numbered and diacritic formats and an option that removes tones. It also shows erhua examples. Keep the form with tones for display and store a toneless form separately if you need it for lookup. Test spacing and erhua with your own inputs before using the output as a search key.

segment() returns words with their pinyin already joined

Chinese word segmentation is one of the features the repository description lists.

Use ruby markup for pronunciation above the characters

The [HTML API](https://pinyin-pro.cn/use/html.html) generates pronunciation markup for display in a browser. Start with a short phrase containing both Chinese characters and punctuation and check the rendering in your own font. Ruby is useful for an annotated reading view. If your application accepts arbitrary user input, confirm how each inserted fragment is escaped and apply the same sanitising rules you use for other generated markup.

The accuracy and speed numbers come from scripts in the repository

The root package.json lists two other packages, `pinyin` and `@napi-rs/pinyin`, as devDependencies, and exposes `compare`, `speed` and `accuracy` scripts that run inside the pinyin-pro package.

Tree shaking works per API, and convert is the exception

The root package.json has a `size` script, `pnpm --filter pinyin-pro size`, for the package's bundle size.

A pnpm workspace of three packages, on Node 18 or newer

The repository is a monorepo, and the published library is one package inside it. The root package.json describes it as the monorepo for pinyin-pro, @pinyin-pro/data and pinyin-pro documentation, with separate Chinese and English docs packages. The root package.json is named pinyin-pro-repository, marked private, and its version field reads 1.0.0, which is unrelated to the library versions: the recent releases are 3.29.5 on 2026-10-10, 3.29.4 on 2026-09-11 and 3.29.3 on 2026-08-19.

The tooling is pinned in the file. `packageManager` is [email protected] and `engines` asks for Node 18 or newer, so an older runtime is out by declaration rather than by surprise. The scripts delegate into the workspace with filters, for example `pnpm --filter pinyin-pro test` and `pnpm --filter @pinyin-pro/data build`, and there are dedicated ones for the benchmarks and the size report: `compare`, `speed`, `accuracy` and `size`. Documentation builds are separate again, with `build:docs`, `deploy:docs` running `bash ./deploy.sh`, and a dev server per language.

Installing the library is the short version of all this. `npm install pinyin-pro` for a project.

Editorial conclusion

pinyin-pro fits a JavaScript or TypeScript product that needs Chinese-to-pinyin conversion with tone marks, multi-pronunciation characters, surname readings, pinyin matching or word segmentation. Before you commit, run the repository's accuracy and speed scripts yourself, since the comparison against pinyin and @napi-rs/pinyin is the maintainer's own, and check that your Node version clears the stated floor of 18.

Frequently asked questions

How do I install pinyin-pro?

From npm with `npm install pinyin-pro`. The package is MIT licensed, and the repository asks for Node 18 or newer.

How do I convert Chinese text to pinyin without tone marks?

The repository description lists tone marks, initials and finals among the outputs; the documentation at pinyin-pro.cn covers the available options.

How does pinyin-pro handle polyphonic characters?

The repository description lists multi-pronunciation characters and surname pinyin among its features.

How big is the pinyin-pro bundle?

The root package.json provides a `size` script, `pnpm --filter pinyin-pro size`, for measuring it.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. zh-lx/pinyin-pro on GitHub

Was this useful?