pinyin-pro

pinyin-pro is a TypeScript library that converts Chinese characters into pinyin with a claimed 99.8% accuracy rate, well ahead of older alternatives like the pinyin package. It exposes a focused set of functions covering the full range of pinyin needs: full pinyin with tone marks or numeric tones, initials/finals extraction, tone-sandhi handling, polyphonic (multi-pronunciation) character disambiguation, surname-aware name pinyin, pinyin-to-character fuzzy matching, HTML ruby-annotation output, and simplified/traditional conversion.

It ships as a zero-runtime-dependency package that works in both Node.js and the browser, with bundled dictionaries for common characters plus optional extension dictionaries for rarer ones. Benchmarks in the README show it converting large batches of text in milliseconds where naive dictionary-lookup libraries take hundreds of milliseconds, making it a practical drop-in for search, IME, and educational tooling that needs to reason about Chinese pronunciation.

What You Get

• A pinyin() function returning full pinyin with configurable tone style (marks, numeric, or none) and output shape (string or array)
• match() for fuzzy text-to-pinyin matching, useful for building search-as-you-type over Chinese content using first letters or full pinyin
• convert() for converting between tone-mark and tone-number pinyin formats, including retroflex (erhua) handling
• html() for generating ruby-annotated HTML so pinyin can be rendered above Chinese characters in the browser
• polyphonic(), customPinyin(), and addDict()/removeDict() for handling multi-pronunciation characters and extending the built-in dictionary
• segment() for Chinese word segmentation using max-probability, min-tokenization, or reverse-max-match algorithms

Common Use Cases

• Adding pinyin search/filtering to a Chinese-language site or admin panel (e.g. matching “zwp” against 中文拼音)
• Generating furigana-style pinyin annotations above Chinese text for language-learning apps
• Building input-method-editor (IME) style lookups or sorting Chinese names/words alphabetically by pinyin
• Preprocessing Chinese text for search indexing, romanization, or text-to-speech pipelines

Under The Hood

Architecture — The library is organized around lib/index.ts, which re-exports a set of independent core/ modules (pinyin, match, html, polyphonic, convert, segment, custom, dict, traditional), each wrapping a shared common/ layer of constants, types, and a hand-rolled Chinese word-segmentation engine (common/segmentit, with max-probability, min-tokenization, and reverse-max-match strategies). Character-to-pinyin lookups run through a middleware pipeline (core/pinyin/middlewares.ts) that layers tone-sandhi correction, surname detection, and polyphonic resolution on top of a base dictionary lookup, so each concern is isolated and independently testable. Tech Stack — Pure TypeScript with no runtime dependencies; the project builds dual ESM/CJS bundles via Rollup (rollup.config.js / rollup.esm.config.js), types are hand-written under types/, and dictionaries are split across several lib/data/dict*.ts files (bundled) with an optional @pinyin-pro/data package for extended coverage, keeping the default install lean. Code Quality — The test/ directory contains 19+ Vitest suites covering tone types, matching, segmentation, surnames, polyphonic handling, and edge cases like double-width Unicode, run with vitest run --coverage and tracked via Codecov; ESLint plus TypeScript strict typings enforce consistency, and the accuracy/speed claims in the README are backed by checked-in benchmark scripts (benchmark/accuracy.js, benchmark/speed.js) rather than just asserted. API Design — The public surface is a small number of purpose-named functions (pinyin, match, convert, html, segment, polyphonic) each with a plain options object (e.g. { toneType, type }), so common tasks are one-liners while advanced behavior (custom dictionaries, tone formats) is opt-in via extra fields rather than separate APIs — this keeps the learning curve shallow for the 80% use case.