Support & FAQ
Find answers to common questions about installation, features, and troubleshooting.
Installation & Setup
How do I install EZPinyin on macOS?
1. Download the EZPinyin-Installer-1.0.pkg file from the homepage
2. Double-click the installer and follow the prompts
3. Log out and log back in (important!)
4. Open System Preferences → Keyboard → Input Sources
5. Click the + button and select "EZPinyin" from the list
6. Set a keyboard shortcut to switch to EZPinyin (or use the menu bar)
How do I enable the EZPinyin keyboard on iOS?
1. Download and install the EZPinyin app from the App Store
2. Open Settings → Keyboard → Keyboards
3. Tap "Add New Keyboard..."
4. Select "EZPinyin"
5. Toggle "Allow Full Access" to enable full keyboard functionality
6. In any app with text input, long-press the globe icon to switch keyboards
What are the system requirements?
macOS: 11.0 (Big Sur) or later
iOS: 14.0 or later
Using the Keyboard
How do I select characters?
EZPinyin shows you a list of character candidates as you type. You can select them in several ways:
On macOS: Use number keys (1-9), Tab/Shift+Tab to cycle, arrow keys to navigate, or click directly
On iOS: Tap a candidate from the suggestion bar, or use number row if available
Can I type English while using EZPinyin?
Yes! Capitalize the first letter of any word and EZPinyin will treat it as English:
ni hao → 你好
Ni hao → Ni 好
This is perfect for typing names and English words mixed with Chinese.
How do I type punctuation in Chinese?
Type English punctuation and EZPinyin automatically converts it to Chinese punctuation:
. → 。
, → ，
! → ！
? → ？
This works for 37 common punctuation marks and symbols.
Features
Does EZPinyin track my typing?
No. EZPinyin is fully offline and doesn't send any data to external servers. Your typing is private and stays on your device.
Why are certain characters shown first?
Characters are sorted by frequency—how often they appear in real Chinese text. This is based on the Jun Da Modern Chinese Frequency List, which analyzes millions of words from books, newspapers, and online sources. The most common characters appear first, so you need fewer keystrokes to find the character you want.
What is HSK integration?
HSK (Chinese proficiency test) vocabulary is prioritized in suggestions. This means beginner-friendly words and characters appear higher in the list, making it easier for learners to find the most useful words first. HSK 1-2 words get extra priority as they're the most fundamental.
How big is the dictionary?
EZPinyin includes 124,000+ character entries and phrases from CC-CEDICT, one of the most comprehensive open-source Chinese-English dictionaries. This includes everything from common everyday words to rare classical characters.
Can I use EZPinyin without internet?
Yes! All dictionary data is stored entirely on your device. EZPinyin works completely offline—you don't need an internet connection to type Chinese.
Troubleshooting
The keyboard isn't showing up on macOS
Solution: Make sure you logged out and logged back in after installation. Input methods require a session restart to become available. If you still don't see it:
1. Check System Preferences → Keyboard → Input Sources
2. Try clicking the + button to manually add EZPinyin
3. If it's still not there, try reinstalling the package
iOS keyboard crashes or disappears
This is rare, but if it happens:
1. Force-quit the app (swipe up from home or use App Switcher)
2. Restart your device
3. Re-enable the keyboard in Settings
Why this happens: Keyboard extensions have a strict 50MB memory limit. If the keyboard uses too much memory, iOS will automatically terminate it (jetsam). This is rare in normal usage, but can happen if you're using an older device with limited RAM.
The candidate window appears in the wrong place on macOS
Solution: This can happen in some text editors. Try:
1. Make sure the application is fully updated
2. Try typing in a different application (Safari, Mail, etc.) to see if the issue is app-specific
3. If you're using a third-party text editor, check its accessibility settings
Some legacy applications may have compatibility issues. Please report any specific cases on GitHub.
I get incorrect candidates for my input
Make sure you're typing Standard Mandarin pinyin:
• Use only the 25 pinyin consonants and vowels (no special characters except apostrophe)
• Don't include tone marks—EZPinyin works with tone-less pinyin
• Use lowercase letters (shift is for English mode)
If you're doing all this and still seeing issues, the character might be a rare entry in the dictionary. Common characters should always show correct suggestions.
The keyboard won't enable on iOS even after tapping "Allow Full Access"
Solution: Try these steps:
1. Go to Settings → Keyboard → Keyboards and remove EZPinyin
2. Force-quit the EZPinyin app
3. Go back and add EZPinyin again
4. When prompted, tap "Allow Full Access"
5. Restart your device
If this still doesn't work, try uninstalling and reinstalling the app from the App Store.
Data & Attribution
Where does the dictionary data come from?
EZPinyin uses the following open-source and academic resources:
Dictionary: CC-CEDICT (Creative Commons Attribution-ShareAlike 4.0)
Frequency Data: Jun Da Modern Chinese Frequency List (academic research)
HSK Levels: Official HSK 3.0 vocabulary lists
All of these resources are freely available and openly licensed. EZPinyin respects these licenses and is built entirely on open-source data.
Still Need Help?
If you can't find an answer above, please contact us at grahambohm@gmail.com to report a bug, suggest a feature, or ask any questions.