How guaguastandup/zotero-pdf2zh works
Zotero PDF2zh is a Zotero add-on plus a local Python service for translating PDFs while preserving layout and supporting bilingual output, cropping, batch work, and configurable LLM services. The principal flow begins in Zotero, reaches the add-on’s translation worker and server, runs a translation task, and makes translated files available as attachments. The graph also includes configuration, environment management, and package updates. Some server and plugin implementations were not excerpted; those branches rely on README capabilities and source-index references rather than inspected call details.
Main entry points: server.py HTTP service · pdf2zhHelper.ts PDF worker · hooks.ts Lifecycle hooks · pdf2zh.ts PDF actions
Components 22
Zotero Add-on
- Plugin entry
plugin/src/index.ts - Lifecycle hooks
plugin/src/hooks.ts - PDF actions
plugin/src/modules/pdf2zh.ts - PDF worker
plugin/src/modules/pdf2zhHelper.ts - File processing
plugin/src/modules/pdf2zhFileProcessor.ts - Attachment handling
plugin/src/modules/pdf2zhAttachmentUtils.ts - Preferences UI
plugin/src/modules/preferenceScript.ts - LLM configurations
plugin/src/modules/llmApiManager.ts
Translation Service
- HTTP service
server/server.py - Task tracking
server/utils/task_manager.py - Translation config
server/utils/config.py - PDF cropping
server/utils/cropper.py
Translation Runtime
- Engine execution
server/utils/execute.py - PDF2zh engines
Environment and Updates
- Managed environments
server/utils/environment_lifecycle.py - Environment detection
server/utils/venv.py - Package sources
server/utils/package_network.py - Package updates
server/utils/auto_update.py - Update command
server/update_packages.py
Other components
- Zotero user
- Zotero
- LLM services
Connections 24
- Zotero user → PDF actions: starts PDF action
- Plugin entry → Lifecycle hooks: initializes
plugin/src/index.ts - Lifecycle hooks → PDF actions: registers actions
plugin/src/hooks.ts - Lifecycle hooks → PDF worker: dispatches tasks
plugin/src/hooks.ts - Lifecycle hooks → Preferences UI: loads preferences
plugin/src/hooks.ts - PDF actions → Zotero: adds Zotero UI
- PDF worker → File processing: uses
plugin/src/modules/pdf2zhHelper.ts - PDF worker → Attachment handling: validates attachments
plugin/src/modules/pdf2zhHelper.ts - PDF worker → HTTP service: sends translation requests
- HTTP service → Task tracking: tracks tasks
server/server.py - HTTP service → Translation config: loads configuration
server/server.py - HTTP service → PDF cropping: uses crop operations
server/server.py - HTTP service → Engine execution: runs translation
server/server.py - Engine execution → PDF2zh engines: invokes engine
- PDF2zh engines → LLM services: uses configured services
- HTTP service → Managed environments: manages runtime
server/server.py - HTTP service → Environment detection: detects environment
server/server.py - Managed environments → Package sources: selects package sources
server/utils/environment_lifecycle.py - HTTP service → Package updates: checks updates
server/server.py - Update command → Managed environments: updates environment
server/update_packages.py - Preferences UI → LLM configurations: manages configurations
plugin/src/modules/preferenceScript.ts - LLM configurations → PDF worker: supplies active config
plugin/src/modules/pdf2zhHelper.ts - HTTP service → PDF worker: returns task results
- PDF worker → Zotero: adds translated attachments