[Plugin] Calibre Book Translator AI (w/Gemini API)

[doctoraisolution]

Hello, Calibre community!

I would like to present Calibre Editorial Translator, a powerful and robust third-party Calibre plugin designed to translate entire EPUB books using Google’s Gemini API (supporting both Free Tier and Paid/Tier 1 APIs).

While Calibre already includes a built-in AI translation feature, this plugin was built from the ground up to address major limitations in standard tools, ensuring a professional, publication-grade layout and maintaining absolute contextual consistency across the entire book.

🚀 What makes this plugin different?
Chapter-Based Translation (Maintains Global Context):

Standard Calibre tool: Often translates text in isolated, small fragments, leading to broken narrative continuity, inconsistent pronoun genders, and lost character terms.

Editorial Translator: Analyzes and processes content chapter-by-chapter and block-by-block while preserving the <spine> reading order, keeping the full context intact.

Automated Translation Guide (System Instructions):

Before translating, the plugin analyzes the complete text of the book and generates a specialized Translation Guide tailored to the work's genre (Light Novel/Manga, Medical/Technical, General Fiction, or Academic Essay).

This guide locks in RAE (Royal Spanish Academy) dialogue conventions (using long dashes —), character gender consistency, and a custom glossary of 30–50 recurring terms/locations.

Advanced Image & Cover Translation:

Unlike tools that ignore embedded images or leave English text in illustrations and maps, this plugin features an Integral Image Manager.

It lets you inspect all images in the EPUB, select the cover or interior illustrations, and send them directly to Gemini's multimodal models (gemini-3.1-flash-image) with custom prompts. It automatically converts and formats the generated image back into the EPUB's original format (JPEG/PNG) while keeping typography and artwork style intact.

Robust Fault Tolerance & Local State Management:

Local State Caching: Progress, partial chunks, and translation caches are stored safely outside the Calibre library (config_dir/plugins/traductor_editorial_work/) to ensure library integrity.

Automatic Subdivision & Recovery: If a block exceeds output limits (MAX_TOKENS) or encounters filters, the engine automatically subdivides the XHTML DOM nodes recursively.

Safety Filters Bypass: Configured with BLOCK_NONE across all categories to prevent false-positive blocks on fictional or technical text.

Cost & Quota Efficiency:

Includes built-in rate-limit handling for Free Tiers (preventative pauses) and instant high-speed execution mode for Paid / Tier 1 APIs, alongside real-time token tracking.

📂 Installation & Usage
Download the .zip package

In Calibre, go to Preferences -> Plugins -> Load plugin from file and select the zip archive.

Restart Calibre, click the Editorial Translator icon on your toolbar, select an EPUB book, and configure your Gemini API Key in Tab 4.

🛠️ Tech Stack
Python 3.9+ with BeautifulSoup4 and PIL (Pillow).

Direct REST communication with Google AI Studio (generateContent endpoints).

Feedback, suggestions, and contributions are more than welcome! Let me know what you think or if you encounter any issues.