Cantonese & Mandarin Popup Dictionary

Overview

One of the struggles with learning a language like Mandarin or Cantonese is quickly looking up characters in dictionaries. For me specifically this required either vaguely remembering the pronunciation, using OCR or manually drawing the strokes in a dictionary.

This problem has been solved in part thanks to Zhongwen, a dictionary that pops up a new window whenever you hover over a character or a word. Similar solutions exist for Cantonese.

However, I quickly ran into a problem when attempting to learn both languages: there is no dictionary that combines both. I got to work to refactor some of the Zhongwen code to make it easier to add in a new language, and attempted to push the changes upstream . I did not get a yes or no response, and figured most likely adding Cantonese would expand the scope of the original extension outside of what the author intended - hence the fork.

Development

One of the first things I did was a refactor of the codebase to make it more readable while adding in support for the Cantonese dictionary, and multiple definitions. This was enough to get something out of the door back in 2020 and have it released.

Since then I have handled a few contributions , before I decided in 2024 to put the time in for a Manifest V3 migration. I decided to tackle it slowly by first building up a test suite as I go, and building it around all existing functionality, while slowly refactoring and migrating the extension.

First I built up simple unit tests around the non-browser specific functionality - eg. searching in the dictionary, creating the dictionary, adding words to a word list etc. This moved a core of the code out of the browser and into specific classes/modules that could be tested separately.

Then Puppeeter could handle the end-to-end browser tests, as seen in this example. When run, the test cases could also be followed live to see any erroneous or quirky behaviour.

The tests gave me plenty of confidence that the migration is going well, and provided a nice base for any future contributions or stress-free dictionary file updates.

Audience

I did not expect my user base to be large - it is somewhat of an intersection betwween Mandarin learners and Hong-Kong Cantonese learners (or, I should say, Cantonese learners who are familiar with Jyupting romanization). As of Jan 2026 the user base of the Chrome Extension is 650+ users and steadily growing.