LexiBridge

LexiBridge is a free, open-source Chrome extension for people learning English: on an English page it marks only the words you don’t know yet. Click a word to see its definition, and take it out once you know it. It never translates the page, and your data stays in your browser.

For learners: 简体中文 · 繁體中文 · 日本語

• Definitions in Simplified Chinese, Traditional Chinese or Japanese, each with four English levels to pick from
• Install: Chrome Web Store (also works in Edge and other Chromium browsers); for a manual install see the install guide
• Website: https://chanmo.github.io/LexiBridge/
• License: MIT (LICENSE); the sources and licenses of the bundled data are in THIRD_PARTY_NOTICES.md

The name

LexiBridge joins “lexicon” and “bridge”: the extension connects you with the words of another language.

Development

No dependencies and no build step: in chrome://extensions, click “Load unpacked” and pick the repository root.

npm test          # unit tests (node:test)
npm run test:browser # real Chrome DOM and interaction regressions
npm run package   # writes dist/lexibridge-<version>.zip, the file uploaded to the stores

• lexicon.js: tokenizing, lemmatizing and definition parsing, shared by the content script, the pages and the tests
• script.js: the content script; highlights words and handles interaction
• ui.js: the word card, the add-word button, and the feedback animation and undo after marking a word known (Shadow DOM, so page styles don’t reach it)
• background.js: install and upgrade, TTS pronunciation, definition lookups in the bundled dictionary
• popup.*: the popup behind the toolbar icon
• options.*, level.*, blacklist.*: the extension pages (word list, English level, disabled sites); they share pages.css and page.js
• packs.js: the language packs and their levels; reads the generated dictionary and level lists under packs/
• i18n.js, _locales/: interface text (chrome.i18n, follows the browser language); data-i18n in pages, t() in scripts
• migrate.js: the upgrade from v1.3: refreshes the old bundled definitions and moves the word list to the new levels, keeping the words taken out and added
• review.js: the one-time store review invitation at the top of the popup (after 7 days and 50 words marked known, counted in knownCount by script.js), and the store link of the always-there rate links (popup and pages sidebar), chosen by extension id; EDGE_ADDON_ID is filled in once listed on Edge Add-ons
• engines/en-irregular.js, packs/: data generated by tools/build_packs.py; don’t edit by hand
• icons/: SVG sources of the icon (store 128 / full-bleed / small toolbar sizes) and the interface icons ui.svg; icons/render.js exports the PNGs

Browser regression checks

npm run test:browser runs the content script, word-card UI and background word operations in a fresh headless Chrome profile. It uses the real browser’s DOM, Range, Highlight and Popover APIs; Chrome extension APIs are stubbed. There are no npm dependencies. Set CHROME_BIN if Chrome/Chromium is not in a usual install location. node tools/check-browser.js --prepare prints a local test page to open manually; it keeps its temporary folder for inspection.

The checks cover text edits, feed inserts, node reuse and remounts, editing and hidden regions, card dismissal and positioning, link hover, native popover coexistence, saving/undo, write failures and late lookups. They complement live site checks: on X, scroll through several loads, expand a post, open its detail, return to the feed, and verify link/like/reply/selection behavior. The fixture does not certify X compatibility, iframes, or text inside a site’s shadow roots.

Dictionary data

The data under packs/ and engines/ is generated by tools/build_packs.py. Definitions come from ECDICT (MIT). Traditional Chinese is converted with OpenCC (s2tw) plus the Taiwan wording in tools/zh-hant-phrases.tsv. The Traditional Chinese and Japanese levels come from the CEFR-J Wordlist, and the Japanese definitions from EJDict-hand (CC0). The generated files are committed, so the tool only needs to run when the data changes. Its dependencies go in env/, pinned in tools/requirements.txt:

python3 -m venv env && env/bin/pip install -r tools/requirements.txt
env/bin/python tools/build_packs.py fetch   # download the data listed in tools/sources.lock.json into vendor/ and verify it
env/bin/python tools/build_packs.py build   # generate packs/ and engines/
env/bin/python tools/build_packs.py check   # check that the committed data matches the build

Sources and licenses are in THIRD_PARTY_NOTICES.md.

Website

docs/ holds the Jekyll sources, built by GitHub Pages itself (Settings → Pages → Deploy from a branch → main / docs). Nothing is built locally and no build output is committed. It uses only the Jekyll that GitHub Pages ships with: no theme, no plugins.

• _config.yml: site variables such as the store and GitHub links; the “Add to Edge” buttons show up once edge_store_url is filled in
• _data/ui.yml: the text every page shares (navigation, buttons, footer) and the path prefix, per language
• index.html, install.md, privacy.md: the Simplified Chinese home page, install guide and privacy policy; zh-TW/ and ja/ hold the same pages in Traditional Chinese and Japanese
• _layouts/, _includes/: the page skeleton, the header (with the language menu) and the footer. A first visit goes to the pages in the browser’s language; a pick in the language menu wins from then on
• assets/demo.js: the clickable demo on the home page, with definitions in the page’s language
• assets/site.css: the site’s styles; same brand colours as the extension, with a dark mode
• sitemap.xml: written by hand; add new pages to it

To add a language: add its text to _data/ui.yml, create a folder of the same name with the three pages (set lang in the front matter), extend the browser-language check in _layouts/default.html and the definitions in assets/demo.js, then add the URLs to sitemap.xml.

Local preview (optional): jekyll serve --source docs, then open http://localhost:4000/LexiBridge/

Releasing

1. Bump the version in manifest.json and package.json, and commit as vX.Y.Z
2. npm test, then npm run package to build the zip
3. Tag and push: git tag vX.Y.Z && git push origin main vX.Y.Z
4. Create the release with the zip attached: gh release create vX.Y.Z dist/lexibridge-X.Y.Z.zip --title vX.Y.Z --notes "..." (the website’s manual install points at this zip in the latest release)
5. Upload the zip to the stores. When the detailed description changes, paste it from store/listing.md into each store’s dashboard (the name and summary come from _locales/)

Brand

Ink and highlighter: ink blue #1f2a44 is the main colour, highlighter gold #f5b83d the marking colour, paper #f7f1e3 the background. Underline highlights on web pages use #c98400. The highlight colours stay away from blue and purple (links) and red (spelling errors).

• [ ] CSV support for import and export