Polili Pinyin Guide

What pinyin is — and why it matters

Pinyin (拼音, pīnyīn) is the official romanization system for Mandarin Chinese. It maps every syllable in Standard Chinese to a Latin-alphabet spelling plus a tone diacritic mark, letting learners pronounce words correctly without knowing how to write the characters.

This is the core problem Polili solves: Chinese has no alphabet, no spaces between words, and four tones that completely change meaning. Without pinyin, a learner staring at 学习中文很有意思 has no way to know how to say it. The Polili pinyin overlay surfaces this information in context, above every character, without interrupting reading or viewing.

The four tones — what the diacritics mean

Mandarin has four tones plus a neutral tone. Polili renders all five using Unicode diacritics:

Character	Pinyin	Tone description	Contour
妈	mā	1st tone — high, flat	ˉ (macron)
麻	má	2nd tone — rising	ˊ (acute)
马	mǎ	3rd tone — dipping	ˇ (caron)
骂	mà	4th tone — falling	ˋ (grave)
吗	ma	Neutral — unstressed	(no mark)

All four characters above are romanized "ma" — the tone mark is the only difference. Polili uses the pinyin-pro library (v3.28) for tone-accurate rendering, which handles tone sandhi (the rule that changes 3rd+3rd → 2nd+3rd) and erhua (er-ization) correctly in context.

How the web-page pinyin overlay works

When you toggle Pinyin on every character in the Polili popup, the content script uses a TreeWalker to scan every text node in the DOM. For each run of consecutive CJK characters (Unicode ranges U+4E00–U+9FFF and U+3400–U+4DBF), Polili:

1. Segments the run into words using pinyin-pro's segmenter — this groups 学习 as one word rather than two unrelated characters.
2. Wraps each word in a <span class="polili-word"> with a data-pinyin attribute.
3. Wraps each character in a <ruby> element with a <rt> tag containing the tone-marked syllable — this is standard HTML ruby annotation, supported in all modern browsers.

The operation runs in idle-callback chunks of 40 nodes at a time to avoid blocking the browser's main thread. A MutationObserver picks up dynamically added content (infinite scroll, SPA navigation) automatically.

The hover dictionary — CC-CEDICT pop-up definition reader

Hovering over any character shows a tooltip with: the character(s), the tone-marked pinyin, and the English definition. Definitions come from the CC-CEDICT dictionary — a community-maintained, freely licensed Chinese-English dictionary with over 100,000 entries.

How the lookup pipeline works

A small starter dictionary (~60 high-frequency words) is inlined in the content script for instant zero-latency lookup. Words not in the starter set are sent to the Polili background service worker, which lazy-loads data/cedict.json (~6.9 MB) on first use and caches it in memory for the browser session. Subsequent lookups are sub-millisecond.

Selecting multiple characters — compound word detection

Text-select two or more Chinese characters to look up the compound word rather than individual characters. For example, selecting 中国 returns "China" — not "middle" + "country" separately. The tooltip positions itself below the selected text range automatically.

Click any character to hear it

Clicking any character or word span triggers the Web Speech API with lang="zh-CN". This uses the operating system's built-in Mandarin voice — no server call, no usage limit. On Windows, the Microsoft Huihui or Microsoft Yaoyao voice is used if installed. On macOS, Tingting or Meijia.

Using the pinyin overlay on video subtitles

In Video Mode, Polili reads the subtitle characters from the screen via PaddleOCR and then runs the same pinyin-pro pipeline to generate the floating overlay. The overlay renders above the subtitle strip in the video, with each pinyin syllable horizontally centered over its corresponding character. You can adjust the size, gap, color, and position using the D-pad controls in the Polili panel. See the OCR Precision guide for tips on maximizing accuracy.