tessl/npm-pinyin

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Output Styles

Name: tessl/npm-pinyin
Author: tessl

Seven different Pinyin output formats providing flexibility for various use cases from tone-marked pronunciation guides to search-friendly formats.

Capabilities

Style Types

Complete set of supported Pinyin output styles with multiple format variations for compatibility.

type IPinyinStyle = 
  // Recommended lowercase formats (consistent with output)
  | "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport"
  // Uppercase formats (v2.x compatibility)
  | "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT"
  // Numeric formats (legacy compatibility)
  | 0 | 1 | 2 | 3 | 4 | 5 | 6;

Style Descriptions and Examples

1. TONE Style (Default)

Value: "tone", "TONE", 1
Description: Standard style with tone marks on vowels
Use Case: Pronunciation guides, language learning

pinyin("中心", { style: "tone" });
// Result: [["zhōng"], ["xīn"]]

pinyin("我爱你", { style: "tone" });
// Result: [["wǒ"], ["ài"], ["nǐ"]]

2. TONE2 Style

Value: "tone2", "TONE2", 2
Description: Numeric tones (1-4) appended to Pinyin
Use Case: Text input systems, databases

pinyin("中心", { style: "tone2" });
// Result: [["zhong1"], ["xin1"]]

pinyin("我爱你", { style: "tone2" });
// Result: [["wo3"], ["ai4"], ["ni3"]]

3. TO3NE Style

Value: "to3ne", "TO3NE", 5
Description: Numeric tones (1-4) inserted after initials
Use Case: Specialized romanization systems

pinyin("中心", { style: "to3ne" });
// Result: [["zho1ng"], ["xi1n"]]

pinyin("我爱你", { style: "to3ne" });
// Result: [["wo3"], ["a4i"], ["ni3"]]

4. NORMAL Style

Value: "normal", "NORMAL", 0
Description: Plain Pinyin without tone marks
Use Case: Search, sorting, text processing

pinyin("中心", { style: "normal" });
// Result: [["zhong"], ["xin"]]

pinyin("我爱你", { style: "normal" });
// Result: [["wo"], ["ai"], ["ni"]]

5. INITIALS Style

Value: "initials", "INITIALS", 3
Description: Consonant initials only (声母)
Use Case: Phonetic analysis, indexing

pinyin("中心", { style: "initials" });
// Result: [["zh"], ["x"]]

pinyin("我爱你", { style: "initials" });
// Result: [[""], [""], [""]]  // No initials for these characters

pinyin("北京", { style: "initials" });
// Result: [["b"], ["j"]]

6. FIRST_LETTER Style

Value: "first_letter", "FIRST_LETTER", 4
Description: First letter only
Use Case: Abbreviations, quick indexing

pinyin("中心", { style: "first_letter" });
// Result: [["z"], ["x"]]

pinyin("我爱你", { style: "first_letter" });
// Result: [["w"], ["a"], ["n"]]

7. PASSPORT Style

Value: "passport", "PASSPORT", 6
Description: Uppercase without tones, ü → YU
Use Case: Official documents, passports

pinyin("中心", { style: "passport" });
// Result: [["ZHONG"], ["XIN"]]

pinyin("绿色", { style: "passport" });
// Result: [["LYU"], ["SE"]]  // ü becomes YU

Style Compatibility

Legacy v2.x Constants

The pinyin function object exposes style constants for backward compatibility:

interface IPinyin {
  // Style constants (legacy v2.x compatibility)
  STYLE_TONE: number;        // 1
  STYLE_TONE2: number;       // 2  
  STYLE_TO3NE: number;       // 5
  STYLE_NORMAL: number;      // 0
  STYLE_INITIALS: number;    // 3
  STYLE_FIRST_LETTER: number; // 4
  STYLE_PASSPORT: number;    // 6
}

Usage Examples:

import pinyin from "pinyin";

// Using legacy constants
pinyin("中心", { style: pinyin.STYLE_TONE2 });
// Same as: pinyin("中心", { style: "tone2" });

pinyin("中心", { style: pinyin.STYLE_NORMAL });
// Same as: pinyin("中心", { style: "normal" });

Advanced Style Usage

Style with Multi-pronunciation

Different styles can produce different results when combined with heteronym support:

// Multiple pronunciations with tone marks
pinyin("中", { style: "tone", heteronym: true });
// Result: [["zhōng", "zhòng"]]

// Multiple pronunciations with numeric tones  
pinyin("中", { style: "tone2", heteronym: true });
// Result: [["zhong1", "zhong4"]]

// Initials may deduplicate identical consonants
pinyin("中", { style: "initials", heteronym: true });
// Result: [["zh"]]  // Both pronunciations have same initial

Style with Segmentation

Styles work consistently with segmentation options:

// Tone style with phrase segmentation
pinyin("中国人", { style: "tone", segment: true, group: true });
// Result: [["zhōngguó"], ["rén"]]

// Normal style for search indexing
pinyin("中国人", { style: "normal", segment: true });
// Result: [["zhong"], ["guo"], ["ren"]]

Character-Specific Behavior

Vowel Characters

Characters starting with vowels (a, e, o, i, u, ü) may show different patterns across styles:

pinyin("爱", { style: "initials" });
// Result: [[""]]  // No initial consonant

pinyin("爱", { style: "first_letter" });  
// Result: [["a"]]  // Vowel first letter

Special Characters

Non-Chinese characters are passed through unchanged regardless of style:

pinyin("hello中国", { style: "tone" });
// Result: [["hello"], ["zhōng"], ["guó"]]

pinyin("hello中国", { style: "passport" });
// Result: [["hello"], ["ZHONG"], ["GUO"]]

Install with Tessl CLI