How crimx/ext-saladict works
Project Type and Purpose
• This is a Chrome/Firefox WebExtension that enables inline translation and dictionary lookup. Its functionality spans from content manipulation on webpages (injecting translation UI components) to background processing (handling translation requests, managing settings, syncing data, and interfacing with various dictionary APIs).
• Additionally, it contains a mac-app component designed to package the extension for macOS, giving it a native feel in Apple’s ecosystem.
File Structure to Reveal Components
• Top-Level Directories:
• “src/background”: Contains background scripts including core logic such as audio management, badge updating, context menus, database handling, and sync management. This part of the code orchestrates translation requests, manages browser events, and performs other central functions.
• “src/content”: Includes the content scripts that are injected into web pages. They manage the in-page UI elements (e.g., dictionary panels, tooltips, word editors) and capture user interactions like text selection.
• “src/options”: Provides the configuration pages where users set preferences, manage dictionary settings, and adjust profiles. It’s a rich UI built predominantly with React components and Redux to handle state.
• “src/popup” and “src/quick-search”: These are the entry points for the user interface elements triggered within the browser toolbar. They provide quick access to translation features.
• “src/notebook” and “src/word-editor”: Additional UI pages for features like saving translations and editing words.
• “src/app-config” and “src/components/dictionaries”: Define the configuration, integration, and engine implementations for various external dictionaries (like Bing, Youdao, Cambridge, etc.). These modules encapsulate the business logic for dictionary queries.
• “mac-app”: Contains native packaging files and assets to build a macOS packaged version of the Saladict extension.
• Other directories like “assets”, “config”, “test”, ".storybook", “docs”, etc., handle styling, build tooling, testing, Storybook configurations for UI component documentation, and documentation support.
Architectural Components and Interactions
• Main Components to Include:
• Background Service:
◦ Modules under “src/background” for initialization, audio management, context menus, language management, and sync. Also, the submodules within “src/background/sync-manager” indicate integration with external synchronization (e.g., Ankiconnect, Eudic, Shanbay, WebDAV).
• Content Scripts:
• Options and Popup UIs:
◦ “src/options”, “src/popup”, and “src/quick-search” represent the different UI facets of the extension. They are built with React, use Redux for state management, and allow user customization.
• Dictionary Engines:
◦ The “src/app-config/dicts” and “src/components/dictionaries” directories hold a set of engines for different translation services. Each dictionary component/module has its own configs, locales, and engine logic.
• mac-app Bundle:
◦ The “mac-app” directory represents the standalone macOS packaging, which integrates with the rest of the system, using some of the same entry points but built for native execution via Xcode configurations.
• Relationships and Interactions:
• Communication flows between content scripts and background scripts via the browser’s messaging APIs. For example, user events captured in a web page trigger messages to the background which in turn invoke dictionary lookups.
• The Options and Popup UIs send requests to the background scripts when changing settings or initiating translations.
• The dictionary engine modules interact with remote translation services and provide data back through the background logic.
• The mac-app layer wraps around the primary extension logic for deployment on macOS.
• Shared libraries in “src/_helpers” and “src/app-config” are used across many components ensuring consistency (e.g., for analytics events, configuration merging, and i18n functionalities).
Architectural Patterns and Design Principles
• Separation of Concerns: The project is distinctly split between background logic, content interaction, and configuration UIs. Each component has its own domain.
• Modularization: The dictionary engines are modularized allowing the system to easily add or update integration with external services.
• Message Passing: Communication between the content scripts, background scripts, and UI pages is handled via structured message passing mechanisms, commonly seen in browser extensions.
• Internationalization: There is robust support for multiple locales, as evident from the “src/_locales” and dictionary-specific locales.
• Testability: Extensive testing is provided under the “test” directory with mocks and specs for API calls and component rendering.