pinyin4j Documentation

To use pinyin4j in your Java project, add the following dependency to your pom.xml file. This version is deployed to Maven Central.

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

The library supports an external dictionary to handle polyphonic characters (多音字) and error correction. When configured, the external dictionary will override the pronunciations of matching words in the system dictionary.

To enable an external dictionary, set the MultiPinyinConfig.multiPinyinPath property to the absolute path of your dictionary file.

MultiPinyinConfig.multiPinyinPath="/Users/yiboliu/my_multi_pinyin.txt"

The external dictionary file must follow the same format as the system's multi-pronunciation dictionary. Each line should contain the word followed by its possible pronunciations in parentheses, separated by commas.

Example format: Word (pinyin1,pinyin2,pinyin3)

吸血鬼日记 (xi1,xue4,gui3,ri4,ji4)

Use the PinyinRomanizationTranslator.convertRomanizationSystem method to transform an unformatted Pinyin string from one Romanization system to another.

This method performs the following steps:

1. Extracts the Pinyin string and tone number from the input.
2. Locates the corresponding entry in the mapping document using the sourcePinyinSystem.
3. Retrieves the equivalent representation in the targetPinyinSystem.
4. Re-attaches the original tone number to the new string.

Returns the converted Pinyin string, or null if an error occurs during the conversion process.

Use the convertHanyuPinyinToGwoyeuRomatzyh method to translate unformatted Hanyu Pinyin (including tone numbers) into the Gwoyeu Romatzyh romanization system.

Input Format: The method expects a string containing unformatted Hanyu Pinyin with a tone number (e.g., ma1).

Return Value:

• Returns the corresponding Gwoyeu Romatzyh string.
• Returns null if no mapping is found in the internal resource mapping.

The formatHanyuPinyin method transforms an unformatted Hanyu Pinyin string (typically one containing tone numbers like a1, e2) into a specific desired format based on an HanyuPinyinOutputFormat configuration.

Supported transformations include:

• Tone Types: Removing tone numbers (WITHOUT_TONE) or converting tone numbers to Unicode tone marks (WITH_TONE_MARK).
• V-Char Types: Converting u: to v (WITH_V) or to the Unicode ü character (WITH_U_UNICODE).
• Case Types: Converting the entire string to uppercase (UPPERCASE).

Note: You cannot combine WITH_TONE_MARK with WITH_V or WITH_U_AND_COLON v-char types; doing so will throw a BadHanyuPinyinOutputFormatCombination exception.

The PinyinRomanizationType class provides several static constants representing different Chinese Pinyin Romanization systems. You can use these constants to specify which romanization system should be applied during conversion.

Supported systems include:

• HANYU_PINYIN: Hanyu Pinyin system
• WADEGILES_PINYIN: Wade-Giles Pinyin system
• MPS2_PINYIN: Mandarin Phonetic Symbols 2 (MPS2) Pinyin system
• YALE_PINYIN: Yale Pinyin system
• TONGYONG_PINYIN: Tongyong Pinyin system
• GWOYEU_ROMATZYH: Gwoyeu Romatzyh system