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

> Learn how the wanxiang script handles Chinese heteronyms (多音字) during pypinyin annotation. Discover its approach to character pronunciation by disabling heteronym processing.

- Repository: [amzxyz/rime-lmdg](https://github.com/amzxyz/rime-lmdg)
- Tags: deep-dive
- Published: 2026-02-24

---

**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`](https://github.com/amzxyz/rime-lmdg/blob/main/wanxiang-tools.py), the primary conversion logic at line 287 processes root words with the following call:

```python
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:

```python
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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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:

```python
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:

```python

# 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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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`](https://github.com/amzxyz/rime-lmdg/blob/main/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. "行走").