How jeffminim/romanizeme works
Project type and purpose
• This is a full-stack browser extension (built with Plasmo, React, TypeScript) whose purpose is to romanize non-Latin scripts on arbitrary web pages.
• The extension offers a popup UI for settings and language selection, a background script for orchestration, and content scripts that manipulate the DOM and perform text conversion using modular converter functions.
File structure
• Top-level:
• background.ts – background service worker
• popup.tsx – the extension’s popup UI entry
• contents/ – content scripts and conversion logic
• components/ & core/ – shared UI components (React), including panels and buttons
• hooks/, lib/, types/ – utility functions, custom hooks, type definitions
• locales/ – i18n JSON message bundles
• configuration (tsconfig.json, postcss.config.js, tailwind.config.ts)
• Architectural pattern:
• MVC-like separation between UI (components), logic (hooks, core), and data (settings, i18n)
• Modular converter functions in contents/converter for each script/language
README for additional insights
• Confirms React+Plasmo refactor in v2.0.0, i18n support, Toast notifications, settings panels, and optimized conversion algorithm (contents/process-texts.ts, readability-parser.ts).
• Lists supported scripts and roadmap, indicating an extensible plugin-style converter architecture.
Main components and their interactions
a. UI Layer
• Popup UI (popup.tsx)
• React component library (components/ui, core panels)
• Settings panel (core/settings)
• Toast notifications (components/ui/toast, sonner)
b. Background Service
• background.ts – handles message routing between UI and content scripts, manages persistent settings (browser.storage)
c. Content Scripts
• contents/convert-page.ts & restore-page.ts – entry points injected into web pages
• contents/scan-texts.ts, text-segmenter.ts, readability-parser.ts – DOM scanning & segmentation
• contents/converter/*.ts – per-language conversion logic
• contents/process-texts.ts – orchestration of scanning + conversion + injection of <ruby> annotations
d. Data & Storage
• Settings (core/settings/*) stored via browser.storage APIs
• i18n messages (locales/*) used by hooks/useI18n.ts
• lib/utils.ts, lib/version.ts – shared utilities
e. External Dependencies
• Pinyin-Pro library (for Chinese conversion)
• Browser APIs (storage, tabs, scripting, runtime messaging)
Architectural patterns and design principles
• Modular Converter Registry: each script’s converter is a separate module imported dynamically
• Single-page React UI in popup, following component hierarchy
• Message-based communication: UI ↔ background ↔ content scripts
• Separation of concerns: UI components vs. logic hooks vs. low-level DOM processing