How the Wanxiang Script Handles Chinese Heteronyms (多音字) During Pypinyin Annotation

The wanxiang toolchain explicitly disables Chinese heteronym (多音字) processing by forcing heteronym=False in all pypinyin API calls, returning only the first pronunciation for each character.

The rime-lmdg repository provides the wanxiang toolchain for annotating Chinese dictionary files with tone-marked pinyin. When processing characters with multiple readings—known as heteronyms or 多音字—the script deliberately prioritizes deterministic output over comprehensive pronunciation coverage.

Default Heteronym Handling Strategy

The wanxiang script systematically disables heteronym resolution across all pinyin generation operations. By hardcoding heteronym=False in every pypinyin invocation, the tool ensures each Chinese character maps to exactly one pronunciation—the first entry in pypinyin's internal dictionary.

Core Processing Routine

In wanxiang-tools.py, the primary conversion logic at line 287 processes root words with the following call:

py = pypinyin_func(root, style=Style.TONE, heteronym=False, errors='default')

This single setting determines that only the primary pronunciation will be considered for the entire word.

Per-Character Conversion Paths

For granular control, the script processes individual characters separately in two contexts. At line 301 for normal dictionary lines, and again at line 328 for user database entries, the code extracts only the first element from each pinyin result:

char_py = [p[0] for p in pypinyin_func(word_for_pinyin,
                                      style=Style.TONE,
                                      heteronym=False,
                                      errors='default')]

Both locations explicitly discard alternative pronunciations by indexing [p[0]] and maintaining heteronym=False.

Unused CLI Heteronym Support

While the repository includes a command-line interface in pypinyin/runner.py that exposes a -m/--heteronym flag (lines 76-78), the wanxiang processing scripts never invoke this option. The flag definition allows users to enable multi-pronunciation output when running pypinyin directly, but wanxiang-tools.py bypasses the CLI entirely and calls the Python API with hardcoded parameters.

Practical Impact on Multi-Pronunciation Characters

Consider the character "行" in "银行" (bank), which can be read as háng or xíng. With wanxiang's default settings:

from pypinyin import pinyin, Style

word = "银行"

# Wanxiang's implementation (heteronym=False)

result = [p[0] for p in pinyin(word, style=Style.TONE, heteronym=False)]
print(result)

# Output: ['yín', 'háng']

The alternative pronunciation "xíng" is silently discarded. Contrast this with heteronym-enabled output:

# With heteronym support activated

result = pinyin(word, style=Style.TONE, heteronym=True)
print(result)

# Output: [['yín'], ['háng', 'xíng']]

Enabling Heteronym Processing in Wanxiang

To modify the script for heteronym support, update all three occurrences in wanxiang-tools.py:

1. Line 287: Change heteronym=False to heteronym=True
2. Line 301: Change heteronym=False to heteronym=True
3. Line 328: Change heteronym=False to heteronym=True

Note: Enabling this feature requires updating downstream logic to handle list-of-lists structures rather than flat strings, as each character may return multiple pronunciations.

Summary

• The wanxiang script disables heteronym processing by default to ensure deterministic, single-pronunciation output per character
• All pypinyin calls in wanxiang-tools.py explicitly set heteronym=False at lines 287, 301, and 328
• Multi-pronunciation characters always return their first dictionary entry when processed
• The bundled CLI in pypinyin/runner.py supports -m/--heteronym, but wanxiang does not utilize this interface
• Enabling heteronyms requires source code modification and structural changes to handle multiple pronunciations per character

Frequently Asked Questions

Does wanxiang support multiple pronunciations for Chinese heteronyms?

No. According to the source code in wanxiang-tools.py, the script explicitly disables heteronym support by passing heteronym=False to every pypinyin function call. This ensures only the primary pronunciation is returned for each character, regardless of context.

Where in the code does wanxiang disable heteronym processing?

The heteronym=False parameter appears in three locations within wanxiang-tools.py: line 287 for root word conversion, line 301 for normal line processing, and line 328 for user database entries. All three instances consistently enforce single-pronunciation output.

Can I enable heteronym output without modifying the source code?

No. While the bundled pypinyin CLI supports the -m/--heteronym flag defined in pypinyin/runner.py (lines 76-78), the wanxiang processing script imports and calls the Python API directly. There is no command-line option exposed by wanxiang-tools.py to toggle this behavior.

Which pronunciation does pypinyin return when heteronyms are disabled?

When heteronym=False, pypinyin returns the first entry from its internal dictionary for that specific character. For example, the character "行" consistently returns "háng" rather than "xíng" because háng appears first in pypinyin's internal mapping, regardless of the word context (e.g., "银行" vs. "行走").

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}