It is choosing each character's reading that trips software adding Zhuyin to Chinese text. Across the 208,015 characters that Taiwan's Ministry of Education annotates in its primary-school dictionary, 《國語小字典》, the open-source library pinyin-pro disagrees with Taiwan's dictionary on 1 character in 19 with its default settings, by our count on 2 October 2026. That is a 94.8% match, where any difference in a symbol or tone mark, the neutral-tone dot included, counts against it, and more than one in five short examples have a syllable that differs. The library's own opt-in Traditional dictionary lifts the match to 95.5%; converting the text to Simplified characters before the lookup lifts it to 96.6%.
Writing a known syllable in Zhuyin is the mechanical part, covered with the symbols in our guide to Zhuyin and pinyin. The hard step comes first, when a program decides which reading a character takes in this sentence.
Every converter chooses one reading per character before any symbol appears
The ministry writes the 小字典 for elementary pupils and their teachers, and says it 「基本上參照《國語一字多音審訂表》取音」, taking readings as a rule from its table of characters with more than one reading. Definitions and examples are annotated character by character, so the text carries its own answer key.
We ran its 12,776 annotated definition lines, from version 2019_20260929 of the ministry's open data, through pinyin-pro 3.28.1 and the current 3.29.4, with identical results. A short example is a run of at least four annotated characters, 4.9 on average. The dictionary revised 169 entries earlier in 2026, so the figures belong to that version. The ministry's own conversion system calls its result for more than one character 「僅供參考」, for reference only.
Dictionary readings below appear exactly as printed, in Zhuyin, under CC BY-ND 3.0 TW, credited as its usage note prescribes: 中華民國教育部（Ministry of Education, R.O.C.）。《國語小字典》（版本編號：2019_20260929）網址：http://dict.mini.moe.edu.tw/
A Simplified-first library forgets its word list on Traditional text
The library, downloaded about 1.2 million times from npm in September 2026, picks readings from a word list keyed in Simplified characters. Given 汽車 rather than 汽车, or 於是 rather than 于是, it finds no word and falls back to single-character readings, rare ones for 車, 於 and 乾. On the 61,103 characters with a separate Simplified form, the default matched 91.5%; on characters both scripts share, 96.2%.
Its documentation offers an optional Traditional dictionary and warns that without it, Traditional text may be read less accurately. The package holding it had about 1% of the library's September downloads, and its map supplies no Taiwan readings.
| pinyin-pro setup | All characters | Characters with a Simplified form | Short examples fully matching |
|---|---|---|---|
| Default | 94.8% | 91.5% | 78.0% |
| Its own Traditional dictionary | 95.5% | 92.4% | 80.0% |
| Text converted to Simplified first | 96.6% | 95.7% | 84.8% |
The conversion used OpenCC, an open-source converter, as a lookup key only. Against the default, 4,900 characters came right and 1,128 went wrong, 438 of them 為 read ㄨㄟˋ where the dictionary prints ㄨㄟˊ.
| Word | 《國語小字典》 | pinyin-pro, default | Simplified first |
|---|---|---|---|
| 汽車 | ㄑㄧˋ ㄔㄜ | ㄑㄧˋ ㄐㄩ | ㄑㄧˋ ㄔㄜ |
| 於是 | ㄩˊ ㄕˋ | ㄨ ㄕˋ | ㄩˊ ㄕˋ |
| 什麼 | ㄕㄣˊ ˙ㄇㄜ | ㄕㄣˊ ㄇㄛˊ | ㄕㄣˊ ˙ㄇㄜ |
| 銀行 | ㄧㄣˊ ㄏㄤˊ | ㄧㄣˊ ㄒㄧㄥˊ | ㄧㄣˊ ㄏㄤˊ |
| 星期 | ㄒㄧㄥ ㄑㄧˊ | ㄒㄧㄥ ㄑㄧ | ㄒㄧㄥ ㄑㄧ |
| 垃圾 | ㄌㄜˋ ㄙㄜˋ | ㄌㄚ ㄐㄧ | ㄌㄚ ㄐㄧ |
| 頭髮 | ㄊㄡˊ ㄈㄚˇ | ㄊㄡˊ ㄈㄚˋ | ㄊㄡˊ ˙ㄈㄚ |
Each dictionary reading is the word's first occurrence in its text. The opt-in Traditional dictionary fixes 銀行 and leaves 汽車, 於是 and 什麼 as the default reads them.
Pupils in Taiwan learn a different reading for about 200 characters
Under Taiwan's 2018 curriculum, pupils start Zhuyin in their first ten weeks of elementary school (國小一年級). Mainland and Taiwan readings are two standards, and even the best setup above leaves 星期 and 垃圾 on the mainland one. These are dictionary readings; how people in Taiwan say the words day to day is outside this count.
With default settings, 2,552 disagreements fell on 213 characters where the library's reading is not one the 小字典 gives, 期, 血, 熟, 擊, 微 and 危 among them. Several survive in the ministry's larger 《重編國語辭典修訂本》, read here through the g0v moedict mirror of its data: it lists 熟 with ㄕㄨˊ first and ㄕㄡˊ as the 語音, the colloquial reading; 血 ㄒㄩㄝˋ as the 讀音, the literary one; and 期 ㄑㄧ as a 又音, a variant. Unihan's kMandarin field separates mainland and Taiwan values for only 109 characters, so it is no Taiwan reading table either.
Tone marks explain part of the gap. The dictionary writes the neutral-tone dot in front, omits the first-tone bar, and gives 一 and 不 the tone they take in speech: 一 appears as ㄧˋ 1,068 times and ㄧˊ 569 times. Of the default's 10,794 disagreements, 1,327 concern only where the neutral tone falls, which can depend on meaning.
Our converter assumed it was reading Simplified text
Until 2 October 2026 our Chinese to Zhuyin converter called pinyin-pro with default settings and labelled its output Taiwan-standard, matching the 小字典 on 94.81%. On 2 October 2026 we changed it to look each run of characters up through an OpenCC Simplified copy while showing the characters as typed, to set each character's Zhuyin beside it, and to drop the label. Measured on the changed code, agreement rose to 96.62%, about 1 character in 30. Taiwan school readings remain a known limit: it still writes 星期 and 垃圾 the mainland way. For a syllable you already know, the pinyin and Zhuyin converter needs no reading choice.
Software still remembers the Tongyong spelling Taiwan's rules dropped in 2008
The Ministry of Education of the Republic of China, then in Beijing, promulgated Zhuyin in November 1918. Romanisation standards have changed more often. Gwoyeu Romatzyh was adopted in 1928, followed by the revised Mandarin Phonetic Symbols II in January 1986. In 2002 Taiwan's principles for romanising Chinese made Tongyong Pinyin the default, with exceptions, for place names, passport names, overseas teaching and other transliteration, according to a Wikisource transcription. The ministry's record of the principles lists an amendment in 2003, the switch to Hanyu Pinyin noted by the Executive Yuan on 18 December 2008 and issued on 5 January 2009, and another amendment in 2011.
Taiwan's rule for its own overseas teaching now prefers Hanyu Pinyin wherever a romanisation is used; in 2002 that clause pointed to Tongyong. Microsoft's Traditional Chinese IME still offers a "Taiwan Pinyin" layout and types 注音 as jhu4yin1, a Tongyong-style spelling with jh where Hanyu Pinyin writes zh.
Standard Mandarin ignores the dialect letters in Unicode's Bopomofo blocks
In Unicode 18.0, released on 16 September 2026, the Bopomofo block, U+3100 to U+312F, has 43 of 48 code points assigned, and Mandarin uses 37, ㄅ at U+3105 to ㄩ at U+3129. Three are dialect letters, ㄪ, ㄫ and ㄬ, which the ministry's Zhuyin handbook marks 「國音不用」. Three more came later: ㄭ for the apical vowel, ㄮ, an early form of ㄜ, and ㄯ for a syllabic nasal.
The tone marks are borrowed spacing modifiers; Unicode annotates ˙ U+02D9 as the Mandarin fifth tone, and the look-alike middle dot U+00B7 carries no such note. Bopomofo Extended, U+31A0 to U+31BF, is full at 32 of 32, and its sub-headings name three groups of languages: Minnan and Hakka, Hmu and Ge, and Cantonese.
