or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-conversion.mdindex.mdoutput-styles.mdtext-segmentation.mdutility-functions.md
tile.json

tessl/npm-pinyin

Chinese character to Pinyin conversion with intelligent phrase matching and multiple pronunciation support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pinyin@4.0.x

To install, run

npx @tessl/cli install tessl/npm-pinyin@4.0.0

index.mddocs/

Pinyin

Pinyin is a comprehensive Chinese character to Pinyin conversion library that enables developers to convert Chinese text into Pinyin romanization for pronunciation, search, and sorting applications. It offers intelligent phrase-based matching for accurate Pinyin conversion, supports multiple pronunciation handling for polyphonic characters, provides various Pinyin style formats, and includes basic traditional Chinese character support.

Package Information

  • Package Name: pinyin
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install pinyin

Core Imports

import pinyin from "pinyin";

For individual functions:

import pinyin, { compare, compact } from "pinyin";
import type { IPinyinOptions, IPinyinSegment, IPinyinStyle } from "pinyin";

For CommonJS:

const pinyin = require("pinyin");
const { compare, compact } = require("pinyin");

Basic Usage

import pinyin from "pinyin";

// Basic conversion
console.log(pinyin("中心"));
// Result: [["zhōng"], ["xīn"]]

// Multi-pronunciation support
console.log(pinyin("中心", { heteronym: true }));
// Result: [["zhōng", "zhòng"], ["xīn"]]

// Different styles
console.log(pinyin("中心", { style: "normal" }));
// Result: [["zhong"], ["xin"]]

// With segmentation for better accuracy
console.log(pinyin("中心", { segment: true }));
// Result: [["zhōng"], ["xīn"]]

// Surname mode for names
console.log(pinyin("华夫人", { mode: "surname" }));
// Result: [["huà"], ["fū"], ["rén"]]

Architecture

Pinyin is built around several key components:

  • Core Conversion Engine: Main pinyin() function handling Chinese character to Pinyin conversion
  • Style System: 7 different output formats from tone marks to passport-style uppercase
  • Mode System: Normal and surname-specific conversion modes
  • Segmentation Integration: Support for multiple word segmentation libraries
  • Phrase Dictionary: Intelligent phrase matching for accurate multi-character conversion
  • Utility Functions: Comparison, compacting, and array manipulation helpers

Capabilities

Core Conversion

Main Pinyin conversion functionality with configurable styles, modes, and options. Handles single characters, phrases, and mixed text with intelligent segmentation.

function pinyin(hans: string, options?: IPinyinOptions): string[][];

interface IPinyinOptions {
  style?: IPinyinStyle;
  mode?: IPinyinMode;
  segment?: IPinyinSegment | boolean;
  heteronym?: boolean;
  group?: boolean;
  compact?: boolean;
}

Core Conversion

Output Styles

Seven different Pinyin output formats including tone marks, numeric tones, initials only, and passport-style formatting.

type IPinyinStyle = 
  | "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport"
  | "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT"
  | 0 | 1 | 2 | 3 | 4 | 5 | 6;

Output Styles

Text Segmentation

Integrated support for multiple Chinese text segmentation libraries to improve conversion accuracy for phrases and compound words.

type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba" | "Intl.Segmenter";

Note: Segmentation is handled internally when using the segment option in the main pinyin() function.

Text Segmentation

Utility Functions

Helper functions for comparing Chinese strings by Pinyin pronunciation and manipulating Pinyin result arrays.

function compare(a: string, b: string): number;
function compact(arr: string[][]): string[][];

Utility Functions

Types

Core type definitions used across the package:

type IPinyinMode = "normal" | "surname" | "NORMAL" | "SURNAME";

interface IPinyin {
  (han: string, options?: IPinyinOptions): string[][];
  compare: (a: string, b: string) => number;
  compact: (arr: string[][]) => string[][];
  
  // Style constants (legacy v2.x compatibility)
  STYLE_TONE: number;
  STYLE_TONE2: number;
  STYLE_TO3NE: number;
  STYLE_NORMAL: number;
  STYLE_INITIALS: number;
  STYLE_FIRST_LETTER: number;
  STYLE_PASSPORT: number;
  
  // Mode constants (legacy v2.x compatibility)
  MODE_NORMAL: number;
  MODE_SURNAME: number;
}