Chinese Pinyin Converter

A simple, lightweight, and easy-to-use .NET Standard library for converting Chinese characters to Pinyin.

Originally built this little utility for one of my own projects and decided to share it on NuGet. Hope you find it useful!

Features

• Easy to use: Provides a simple static method for conversion.
• Tone Support: Supports converting to Pinyin with or without tone numbers.
• Character Passthrough: Non-Chinese characters in the text are returned as they are.
• Cross-platform: Built on .NET Standard 2.0, compatible with .NET Framework, .NET Core, .NET 5+, Xamarin, etc.

Getting Started

Installation

You can install the package via the .NET CLI:

dotnet add package CingZeoi.ChinesePinyinConverter

Or via the NuGet Package Manager console in Visual Studio:

Install-Package CingZeoi.ChinesePinyinConverter

Usage

Here's a quick example to get you started:

using System;
using System.Linq;
using ChinesePinyinConverter; // Import the namespace first.

// Your text can contain Chinese, English, numbers, and symbols.
string text = "你好, a programmer! 2025年";

// Example 1: Convert to Pinyin with tone numbers (e.g., "ni3 hao3")
var pinyinWithTone = PinyinConverter.ConvertToPinyin(text, true);
Console.WriteLine(string.Join(" ", pinyinWithTone));
// Output: ni3 hao3, a programmer! 2025 nian2

// Example 2: Convert to Pinyin without tone numbers (e.g., "ni hao")
var pinyinWithoutTone = PinyinConverter.ConvertToPinyin(text, false);
Console.WriteLine(string.Join(" ", pinyinWithoutTone));
// Output: ni hao, a programmer! 2025 nian

A Note on Use Cases & Limitations

that this is not a professional-grade Chinese Pinyin library. Its handling of polyphones (chinese words with multiple pronunciations) is basic.

However, it shines in a specific scenario: fuzzy string matching for homophones. In Chinese, many words can have the exact same Pinyin pronunciation but are written with completely different characters. For example, "富庶" ("fu4 shu4" - prosperous) and "负数" ("fu4 shu4" - negative number) sound identical but are not equal in a direct string comparison.

This library makes it trivial to compare such words phonetically, which is particularly useful for features like fuzzy search or handling user input errors.

Example: Homophone Comparison

string kw1 = "富庶"; // "fù shù" - prosperous
string kw2 = "负数"; // "fù shù" - negative number

// Direct string comparison fails
Console.WriteLine(string.Equals(kw1, kw2));
// Output: false

// Phonetic comparison using the library succeeds
string pinyin1 = string.Join("", PinyinConverter.ConvertToPinyin(kw1));
string pinyin2 = string.Join("", PinyinConverter.ConvertToPinyin(kw2));

Console.WriteLine(string.Equals(pinyin1, pinyin2));
// Output: true

Contributing

Contributions are always welcome! This is a simple project, but if you have a suggestion or find a bug, please feel free to open an issue or submit a pull request.