How to Convert Chinese Text to Pinyin with pinyin‑pro: A Complete Guide

A user asked whether there is a Java library for converting Chinese characters to pinyin; the answer mentioned the pinyin4j library and then introduced a more feature‑rich open‑source project called pinyin‑pro .

pinyin‑pro can perform various conversions: Chinese to pinyin with tones, tone‑less pinyin, numeric tone suffixes, arrays of results, initials, finals, tone numbers, first‑letter abbreviations, polyphone handling, surname mode, non‑Chinese character filtering, custom pinyin definitions, and pinyin‑text matching.

<dependency>
    <groupId>com.belerweb</groupId>
    <artifactId>pinyin4j</artifactId>
    <version>2.5.0</version>
</dependency>

Typical imports for using pinyin‑pro in JavaScript:

import { pinyin } from 'pinyin-pro';
import { customPinyin } from 'pinyin-pro';
import { match } from 'pinyin-pro';

Examples of retrieving pinyin with different options:

pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
<pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'
<pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'
<pinyin('汉语拼音', { type: 'array' }); // ['hàn','yǔ','pīn','yīn']
<pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'
<pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'
<pinyin('好', { multiple: true }); // 'hǎo hào'
<pinyin('赵钱孙李额', { pattern: 'first' }); // 'z q s l é'
<pinyin('我very喜欢你', { nonZh: 'removed' }); // 'wǒ xǐ huān nǐ'

Custom pinyin can be defined via customPinyin:

customPinyin({
  干一行行一行: 'gàn yī háng xíng yī háng'
});
pinyin('干一行行一行'); // 'gàn yī háng xíng yī háng'

The match method checks whether a pinyin string matches a text string, supporting abbreviations and polyphone matching:

match('汉语拼音', 'hanyupinyin'); // [0,1,2,3]
match('汉语拼音', 'hanpin'); // [0,2]
match('会计', 'kuaiji'); // [0,1]
match('会计', 'huiji'); // [0,1] (polyphone match)

Installation is straightforward:

npm install pinyin-pro

yarn add pinyin-pro

Four ways to import the library:

Browser script tag

CommonJS in browser

CommonJS in Node

ESM import

<!-- Browser script example -->
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  console.log(pinyin('汉语拼音'));
</script>

// CommonJS (Node)
const { pinyin } = require('pinyin-pro');
console.log(pinyin('汉语拼音'));

// ESM
import('pinyin-pro').then(exports => {
  console.log(exports.pinyin('汉语拼音'));
});

The project repository is available at https://github.com/Wechat-TJ/TJ-WORLD-FORU for further reference.