Zotero Connectors are browser extensions for Chrome, Firefox, Edge, and Safari that capture bibliographic references from any webpage and save them to a Zotero library. Architecturally the connector is split into two layers that live inside the browser: injected content scripts that run inside every webpage, and a background process that acts as the persistent middle-layer between those scripts and the outside world. Together these two layers communicate with either the locally running Zotero desktop application or, when it is unavailable, with the zotero.org cloud API.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zotero/zotero-connectors/llms.txt
Use this file to discover all available pages before exploring further.
The Four Components
(a) Injected Scripts — run inside each webpage
(a) Injected Scripts — run inside each webpage
Every HTTP/HTTPS page is injected with a complete copy of the Zotero translation framework. The injected bundle (defined by the
injectInclude array in gulpfile.js) includes the full translate engine, HTTP utilities, proxy support, sandbox manager, and the Zotero.Inject namespace that bootstraps everything.A Zotero.Translate.Web instance orchestrates translator detection and runs individual translators against the current page. Custom classes for translator retrieval (src/common/translators.js) and item saving (src/common/itemSaver.js) replace the desktop equivalents and proxy calls through to the background process.(b) Background Process — persistent middle-layer
(b) Background Process — persistent middle-layer
The background process (an event page in MV2 / a service worker in MV3) maintains a cache of translator metadata, performs the initial URL-match translator detection, updates the toolbar icon and badge, stores connector preferences, and routes translated items to Zotero or zotero.org.Browser-specific entry points are
src/browserExt/background.js (shared logic for the Zotero.Connector_Browser namespace) and src/browserExt/background-worker.js (the MV3 service-worker bootstrap that importScripts all background files including keep-mv3-alive.js).(c) Zotero Desktop — connector HTTP server on port 23119
(c) Zotero Desktop — connector HTTP server on port 23119
When Zotero is open it runs a connector HTTP server on port 23119. Calls to
Zotero.Connector.callMethod(endpoint) in the connector codebase translate directly into HTTP requests to this server. The server API accommodates saving items, retrieving translator metadata, checking online status, and more.Communication is always connector-initiated. Zotero cannot reach out to the connector on its own.
(d) zotero.org Web API — fallback when desktop is unavailable
(d) zotero.org Web API — fallback when desktop is unavailable
The Save Flow
User clicks the toolbar button
browser.action.onClicked fires in the background process. _browserAction(tab) is called, which checks for available translators stored in _tabInfo[tab.id].Background kicks off translation
Zotero.Connector_Browser.saveWithTranslator(tab, i) calls Zotero.Messaging.sendMessage("translate", [instanceID, translatorID, options], tab, null), broadcasting to all frames of that tab.Injected script receives the translate message
The
translate message listener registered during Zotero.Inject._addMessageListeners() fires. It checks instanceID to target the correct frame and delegates to Zotero.PageSaving.onTranslate(...).Translators run inside the page
Zotero.Translate.Web runs detectWeb() and then doWeb() in the translator sandbox managed by Zotero.Translate.SandboxManager. Item data is collected in the page context.Key Source Files
| File | Role |
|---|---|
src/common/inject/inject.jsx | Zotero.Inject namespace — bootstraps the inject layer, registers message listeners, handles ZoteroItemUpdated events |
src/browserExt/background.js | Zotero.Connector_Browser — toolbar icon, tab state, translation dispatch, script injection |
src/common/connector.js | Zotero.Connector — HTTP client for the Zotero desktop connector server (port 23119) |
src/common/translators.js | Zotero.Translators — in-memory translator cache, URL-match detection, remote update logic |
src/common/messages.js | MESSAGES registry — defines every monkey-patched RPC method between inject and background |
src/common/messaging.js | Zotero.Messaging (background side) — registers browser.runtime.onMessage, dispatches to handlers |
src/browserExt/messaging_inject.js | Zotero.Messaging (inject side) — monkey-patches all MESSAGES entries, sends via browser.runtime.sendMessage |
gulpfile.js | Build pipeline — defines injectInclude and backgroundInclude script bundles |
Architecture Pages
Inject Scripts
How the full translation framework is injected into webpages and how
Zotero.Inject bootstraps translator detection.Background Process
The persistent middle-layer: translator cache, MV2 vs MV3 differences, offscreen documents, and the keep-alive mechanism.
Message Passing
The typed MESSAGES registry, monkey-patching, hook functions, and Chrome-specific payload chunking.