rocktranslate 1.0.0__tar.gz

rocktranslate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RockTranslate Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rocktranslate-1.0.0/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: rocktranslate
+Version: 1.0.0
+Summary: High-Fidelity AI Layout-Preserved PDF Translator
+Home-page: https://github.com/PerfectWin7777/RockTranslate
+Author: RockTranslate Contributors
+Author-email: wintertony7777@gmail.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4
+Requires-Dist: lxml
+Requires-Dist: litellm
+Requires-Dist: json-repair
+Requires-Dist: pypdf
+Requires-Dist: loguru
+Requires-Dist: tiktoken
+Provides-Extra: gui
+Requires-Dist: PyQt6>=6.4.0; extra == "gui"
+Requires-Dist: PyQt6-WebEngine>=6.4.0; extra == "gui"
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+
+# <img src="src/rocktranslate/assets/rocktranslate_icon.png" width="48" align="center" alt="RockTranslate Icon" /> RockTranslate
+
+<p align="center">
+  <img src="src/rocktranslate/assets/RockTranslate_logo.png" width="480" alt="RockTranslate Logo" />
+</p>
+
+<p align="center">
+  <strong>High-Fidelity AI Layout-Preserved PDF Translator</strong>
+</p>
+
+<p align="center">
+  <!-- High-visibility dynamic download badge -->
+  <a href="https://github.com/PerfectWin7777/RockTranslate/releases/download/v1.0.0/RockTranslate_Setup_v1.0.0.exe">
+    <img src="https://img.shields.io/badge/Download-Windows%20GUI%20Installer-blue?style=for-the-badge&logo=windows&logoColor=white" alt="Download Windows GUI Installer" />
+  </a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" />
+  <img src="https://img.shields.io/badge/Python-3.9+-green.svg" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg" alt="Supported Platforms" />
+</p>
+
+---
+
+### 📥 [Click here to download the standalone Windows Desktop GUI Installer (.exe)](https://github.com/PerfectWin7777/RockTranslate/releases/tag/v1.0.0-beta/RockTranslate_Setup_v1.0.0.exe)
+
+---
+
+## 1. Introduction & Origin Story
+
+> *"RockTranslate breaks the limits of traditional PDF translation. By combining advanced LLMs with high-fidelity geometric DOM mapping, it reconstructs complex scientific papers from publishers like Elsevier and Springer into completely native, translated PDFs."*
+
+### Our Story: Bridging the Academic Inequality Gap
+
+Scientific and academic research is a global endeavor, yet the vast majority of high-impact literature is published in English. For students and researchers in developing nations, particularly in Africa and Cameroon, accessing, translating, and fully understanding these highly complex documents poses a massive challenge [1]. 
+
+Traditional translation tools are either:
+1.  **Prohibitively expensive** or heavily restricted by paid subscription tiers (e.g., DeepL, Google Translate).
+2.  **Lacking visual layout preservation** (e.g., standard text extractors, legacy translation proxies), rendering complex formulas, double-column structures, and tables completely unreadable [2].
+
+**RockTranslate** was born out of academic necessity, created by students facing these exact barriers. It is designed to be a fully accessible, local-first, high-fidelity alternative that allows any researcher, anywhere, to translate academic PDFs without losing their original layout—empowering global education without financial borders [1].
+
+---
+
+## 2. Key Features
+
+RockTranslate is a desktop application designed for translating scientific, technical, and academic PDF documents while preserving their original structure, formatting, figures, tables, and visual layout.
+
+Built with a local-first architecture, RockTranslate prioritizes performance, reliability, and user control. The application combines advanced document analysis, intelligent translation workflows, and high-fidelity PDF reconstruction to deliver professional-quality results.
+
+*   **Layout-Preserved PDF Translation:** Retains the exact geometry, columns, margins, and alignment of the original document [2].
+*   **Scientific and Technical Document Support:** Specially designed to handle mathematical formulas, indices, equations, and proper academic nomenclature.
+*   **High-Fidelity PDF Reconstruction:** Preserves figures, images, and tables in their original spatial coordinates.
+*   **Fast Desktop Performance:** Employs parallel and asynchronous processing to deliver translations without blocking user interfaces [1].
+*   **Lightweight and Responsive User Experience:** Optimized loading speeds and visual feedback indicators.
+*   **Privacy-Conscious Workflow:** Supports offline and local-first execution via local LLMs (Ollama) to guarantee complete data privacy.
+*   **Open-Source and Community-Driven:** Built entirely on open-source foundations, giving control back to the scientific community.
+
+---
+
+
+## 3. Installation
+
+Choose the installation method that best suits your requirements:
+
+### A. Package Installation (via pip)
+Once published on PyPI, you can install the latest stable version of RockTranslate directly:
+```bash
+pip install rocktranslate
+```
+
+### B. Development Installation (via Git)
+For the most up-to-date features, or to run the application directly from source:
+```bash
+# Clone the repository
+git clone https://github.com/PerfectWin7777/RockTranslate.git
+cd RockTranslate
+
+# Install dependencies and the package in editable mode
+pip install -e .
+```
+
+### C. Direct Remote Install
+You can also install the development version directly from GitHub without cloning the repository manually:
+```bash
+pip install git+https://github.com/PerfectWin7777/RockTranslate.git
+```
+
+---
+
+## 4. Visual Demonstration (Before & After)
+
+### Real-Time Application Lifecycle
+*The following animation demonstrates opening, rendering, and translating a multi-column paper dynamically:*
+
+<p align="center">
+  <img src=".github/assets/readme_animation.gif" width="800" alt="RockTranslate Application Demo" />
+</p>
+
+---
+
+### 🔬 1. English to Spanish (Elsevier Double-Column Layout)
+*Demonstrating perfect preservation of multi-column text flow, publisher headers, and author blocks.*
+
+![English to Spanish Comparison](.github/assets/readme_comparison_en_to_spa.png)
+
+*The original Elsevier double-column layout is fully retained with zero text-overlapping or margin drift.*
+
+---
+
+### 🧠 2. English to French (Attention Is All You Need — Abstract & Title)
+*Demonstrating precise preservation of scientific structures, titles, and mathematical equations.*
+
+![English to French Comparison](.github/assets/readme_comparison_en_to_fr.png)
+
+*Mathematical formulas, paragraph flows, and proper academic register remain completely intact.*
+
+---
+
+### 🌸 3. English to Japanese (Attention Is All You Need — Paragraph Flow)
+*Demonstrating robust handling of double-byte CJK characters without vertical line collapses or overlapping.*
+
+![English to Japanese Comparison](.github/assets/readme_comparison_en_to_jn.png)
+
+*Japanese Kanji and Kana characters are rendered cleanly with proportional horizontal scaling.*
+
+---
+
+### 🌸 4. English to German (Elsevier Double-Column Layout— Paragraph Flow and Table)
+*Demonstrating robust preservation of tables and math formulas in a double-column layout..*
+
+![English to German Comparison](.github/assets/readme_comparison_en_to_ge.png)
+
+*Clarity of paragraphs, tables and styles, preservation of mathematical formulas.*
+
+---
+
+## 5. The Three Versions
+
+RockTranslate provides three entry points to support any workflow:
+
+### A. Graphical User Interface (GUI)
+A responsive desktop application featuring:
+*   Synchronized dual-pane viewports (Original PDF vs. Live Translated HTML) [2].
+*   Real-time zoom sliders and page navigation.
+*   Visual shimmer skeleton loaders and real-time status bars [1, 2].
+
+### 📥 [Click here to download the standalone Windows Desktop GUI Installer (.exe)](https://github.com/PerfectWin7777/RockTranslate/releases/tag/v1.0.0-beta/RockTranslate_Setup_v1.0.0.exe)
+
+### B. Command-Line Interface (CLI)
+A lightweight execution engine that can be run globally from the terminal once installed [3].
+
+#### Usage Examples:
+1.  **Translate to French (default) using the default Gemini model:**
+    ```bash
+    rocktranslate article_scientifique.pdf -l French
+    ```
+2.  **Translate to Spanish and save to a custom output file:**
+    ```bash
+    rocktranslate paper.pdf -l Spanish -o report_es.pdf
+    ```
+3.  **Translate to German using OpenAI with an explicit API key:**
+    ```bash
+    rocktranslate document.pdf -m openai/gpt-4o-mini -k YOUR_OPENAI_KEY -l German
+    ```
+4.  **Run fully local translation using Ollama (no API key required):**
+    ```bash
+    rocktranslate document.pdf -m ollama/llama3 -l French
+    ```
+
+---
+
+### 💡 Dynamic Model Routing & Frontier Models Guidance
+
+#### 1. Model Naming Convention (LiteLLM Integration)
+RockTranslate inherits its entire model routing architecture directly from **LiteLLM**. All model identifiers passed through the `-m / --model` CLI flag (or through the API) must strictly follow the standard `provider/model_name` syntax. 
+
+Both the provider prefix and the model name must match the exact naming conventions defined in the [LiteLLM Supported Providers & Models Documentation](https://docs.litellm.ai/docs/providers).
+
+#### 2. Why Frontier Models are Essential for Perfect Visual Layouts
+While local or lightweight models function perfectly, we highly recommend using advanced **frontier models**—such as **Gemini 3.5 Flash**, **GPT 5.5**, **Claude 4.X**, **DeepSeek V4**, **Kimi K2.6**, or **GLM 5.5 ; Any other open-source LLM provider**—for complex scientific papers. 
+
+*   **Instruction-Following & Tag Integrity:** Frontier models possess superior reasoning capabilities. They strictly preserve nested XML style tags (like `<color_HEX>`) and structural JSON mapping arrays, allowing the renderer to position text segments with pixel-perfect accuracy.
+*   **Academic Register & Context:** They avoid literal, broken word-by-word translations of fragmented segments. Instead, they understand the global paragraph context, translating complex double-column academic layouts into natural scientific prose.
+
+
+### C. API Developer Library
+Integrate layout-preserved document translation directly into your Python scripts or data pipelines.
+
+#### Programmatic Integration Scenarios:
+```python
+import os
+from rocktranslate import RockTranslator
+
+# Ensure a sample file is present before initiating diagnostic runs
+sample_pdf = "article_scientifique.pdf"
+
+if not os.path.exists(sample_pdf):
+    print(f"Sample file '{sample_pdf}' not found. Please provide a valid PDF.")
+else:
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 1: Basic Translation (Using Google Gemini with environment key)
+    # ──────────────────────────────────────────────────────────────────────
+    # Automatically searches for GEMINI_API_KEY inside system environment variables.
+    # Uses the advanced Gemini 3.5 Flash model for superior layout preservation.
+    translator_gemini = RockTranslator(
+        model="gemini/gemini-3.5-flash",
+        target_lang="Spanish"
+    )
+    
+    # Executes translation, saving the file to '[article_scientifique]_translated.pdf'
+    success_gemini = translator_gemini.translate(input_pdf_path=sample_pdf)
+    print(f"Scenario 1 complete. Success: {success_gemini}")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 2: Custom Output Path and Language Customization
+    # ──────────────────────────────────────────────────────────────────────
+    translator_custom = RockTranslator(
+        model="gemini/gemini-3.5-flash",
+        target_lang="German"
+    )
+    
+    # Translates to German and writes output to a custom specified path
+    custom_output = "results/german_report.pdf"
+    os.makedirs("results", exist_ok=True)
+    
+    success_custom = translator_custom.translate(
+        input_pdf_path=sample_pdf,
+        output_pdf_path=custom_output
+    )
+    print(f"Scenario 2 complete. Translated PDF written to: {custom_output} (Success: {success_custom})")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 3: Frontier Provider (OpenAI GPT 5.5) with Explicit API Key
+    # ──────────────────────────────────────────────────────────────────────
+    # Explicit credentials pass overrides local environment configurations.
+    # We route the request using the exact LiteLLM naming convention (provider/model_name).
+    # Learn more at: https://docs.litellm.ai/docs/providers
+    translator_openai = RockTranslator(
+        model="openai/gpt-5.5",
+        api_key="sk-your-openai-api-key-here",  # Replace with a valid credentials key
+        target_lang="Italian",
+        temperature=0.3  # Lower temperature for more rigid, literal academic translation
+    )
+    
+    # success_openai = translator_openai.translate(input_pdf_path=sample_pdf)
+    print("Scenario 3 configured. (Run skipped to avoid credential errors.)")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 4: Fully Local and Offline Translation (Using Ollama)
+    # ──────────────────────────────────────────────────────────────────────
+    # No API keys or remote servers required. Ensure Ollama is running on the host machine.
+    translator_local = RockTranslator(
+        model="ollama/llama3",
+        target_lang="French",
+        custom_base_url="http://localhost:11434"  # Default local Ollama gateway port
+    )
+    
+    # success_local = translator_local.translate(input_pdf_path=sample_pdf)
+    print("Scenario 4 configured for local offline execution.")
+```
+
+---
+
+## 6. Known Limitations & Roadmap (TODO)
+
+### Current Limitations:
+*   **The LaTeX FontForge Crash (Windows):** Older standalone versions of `pdf2htmlEX` on Windows occasionally experience segmentation faults or infinite loops when compiling complex, customized LaTeX mathematical fonts (Type-1 vector fonts) [2.2.6].
+    *   *Our Solution:* We have implemented a robust Windows crash preventer (`SetErrorMode`) and a strict 30-second subprocess timeout. If a compilation hangs, RockTranslate instantly terminates the process and fails gracefully in under 50ms without freezing the UI [1].
+
+### Roadmap & Future TODOs:
+*   [ ] **PyQt6 / QWebEngine Migration:** Migrate the Desktop GUI away from PyQt6 and heavy Chromium-based `QWebEngine` wrappers, transitioning towards a lightweight native webview (e.g., `pywebview`). This will reduce the compiled `.exe` bundle size from ~150MB down to under 20MB.
+*   [ ] **Automatic Fallback to Serverless Cloud Conversion:** Integrate an optional, free, or self-hosted serverless cloud rendering API (using the official Docker Linux image) to handle complex LaTeX papers without any local system limitations [1, 2].
+*   [ ] **Concurrent Batch Translation:** Implement parallel API calls (limited to 3 concurrent requests to respect free-tier quotas) to speed up translation times by 3x [1].
+
+---
+
+## 7. Contributing & Community Support
+
+We believe in making scientific literature universally accessible and welcome contributions from researchers, developers, and educators. Here is how you can help advance the project:
+
+*   **Core UI Refactoring:** Help us migrate from the resource-intensive PyQt6/QWebEngine setup to a lightweight `pywebview` client.
+*   **Bug Reports & Edge Cases:** Found a PDF with highly complex LaTeX layout issues? Open an issue and upload the file (or a sample page) so we can optimize our BeautifulSoup parser rules.
+*   **Translation & Localization:** Contribute internationalization files (`.qm`/`.ts` translations) to make the user interface available in more languages.
+*   **Prompt Optimization:** Help us refine the instructions in `prompts.py` to further improve terminology preservation and tag alignment across different languages.
+
+To contribute, please fork the repository, make your changes in a dedicated branch, and submit a pull request. For major architectural modifications, feel free to open an issue first to discuss your ideas with the core maintainers.
+
+---
+
+## 8. Acknowledgements & Credits
+
+RockTranslate stands on the shoulders of giants. We would like to express our deepest gratitude to the open-source projects that made this tool possible:
+*   **pdf2htmlEX:** The geometric engine used to compile PDF structures into HTML [2.2.1] ([GitHub](https://github.com/pdf2htmlEX/pdf2htmlEX)).
+*   **Poppler & FontForge:** The underlying vector engines driving pdf2htmlEX [3.2.4] ([Poppler Website](https://poppler.freedesktop.org/) | [FontForge Website](https://fontforge.org/)).
+*   **LiteLLM:** The multi-provider AI routing wrapper [2.3.1] ([Official Documentation](https://docs.litellm.ai/)).
+*   **BeautifulSoup4 & lxml:** Driving high-speed, programmatic DOM analysis ([BeautifulSoup Documentation](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) | [lxml Website](https://lxml.de/)).

rocktranslate-1.0.0/README.md

@@ -0,0 +1,299 @@
+
+# <img src="src/rocktranslate/assets/rocktranslate_icon.png" width="48" align="center" alt="RockTranslate Icon" /> RockTranslate
+
+<p align="center">
+  <img src="src/rocktranslate/assets/RockTranslate_logo.png" width="480" alt="RockTranslate Logo" />
+</p>
+
+<p align="center">
+  <strong>High-Fidelity AI Layout-Preserved PDF Translator</strong>
+</p>
+
+<p align="center">
+  <!-- High-visibility dynamic download badge -->
+  <a href="https://github.com/PerfectWin7777/RockTranslate/releases/download/v1.0.0/RockTranslate_Setup_v1.0.0.exe">
+    <img src="https://img.shields.io/badge/Download-Windows%20GUI%20Installer-blue?style=for-the-badge&logo=windows&logoColor=white" alt="Download Windows GUI Installer" />
+  </a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" />
+  <img src="https://img.shields.io/badge/Python-3.9+-green.svg" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg" alt="Supported Platforms" />
+</p>
+
+---
+
+### 📥 [Click here to download the standalone Windows Desktop GUI Installer (.exe)](https://github.com/PerfectWin7777/RockTranslate/releases/tag/v1.0.0-beta/RockTranslate_Setup_v1.0.0.exe)
+
+---
+
+## 1. Introduction & Origin Story
+
+> *"RockTranslate breaks the limits of traditional PDF translation. By combining advanced LLMs with high-fidelity geometric DOM mapping, it reconstructs complex scientific papers from publishers like Elsevier and Springer into completely native, translated PDFs."*
+
+### Our Story: Bridging the Academic Inequality Gap
+
+Scientific and academic research is a global endeavor, yet the vast majority of high-impact literature is published in English. For students and researchers in developing nations, particularly in Africa and Cameroon, accessing, translating, and fully understanding these highly complex documents poses a massive challenge [1]. 
+
+Traditional translation tools are either:
+1.  **Prohibitively expensive** or heavily restricted by paid subscription tiers (e.g., DeepL, Google Translate).
+2.  **Lacking visual layout preservation** (e.g., standard text extractors, legacy translation proxies), rendering complex formulas, double-column structures, and tables completely unreadable [2].
+
+**RockTranslate** was born out of academic necessity, created by students facing these exact barriers. It is designed to be a fully accessible, local-first, high-fidelity alternative that allows any researcher, anywhere, to translate academic PDFs without losing their original layout—empowering global education without financial borders [1].
+
+---
+
+## 2. Key Features
+
+RockTranslate is a desktop application designed for translating scientific, technical, and academic PDF documents while preserving their original structure, formatting, figures, tables, and visual layout.
+
+Built with a local-first architecture, RockTranslate prioritizes performance, reliability, and user control. The application combines advanced document analysis, intelligent translation workflows, and high-fidelity PDF reconstruction to deliver professional-quality results.
+
+*   **Layout-Preserved PDF Translation:** Retains the exact geometry, columns, margins, and alignment of the original document [2].
+*   **Scientific and Technical Document Support:** Specially designed to handle mathematical formulas, indices, equations, and proper academic nomenclature.
+*   **High-Fidelity PDF Reconstruction:** Preserves figures, images, and tables in their original spatial coordinates.
+*   **Fast Desktop Performance:** Employs parallel and asynchronous processing to deliver translations without blocking user interfaces [1].
+*   **Lightweight and Responsive User Experience:** Optimized loading speeds and visual feedback indicators.
+*   **Privacy-Conscious Workflow:** Supports offline and local-first execution via local LLMs (Ollama) to guarantee complete data privacy.
+*   **Open-Source and Community-Driven:** Built entirely on open-source foundations, giving control back to the scientific community.
+
+---
+
+
+## 3. Installation
+
+Choose the installation method that best suits your requirements:
+
+### A. Package Installation (via pip)
+Once published on PyPI, you can install the latest stable version of RockTranslate directly:
+```bash
+pip install rocktranslate
+```
+
+### B. Development Installation (via Git)
+For the most up-to-date features, or to run the application directly from source:
+```bash
+# Clone the repository
+git clone https://github.com/PerfectWin7777/RockTranslate.git
+cd RockTranslate
+
+# Install dependencies and the package in editable mode
+pip install -e .
+```
+
+### C. Direct Remote Install
+You can also install the development version directly from GitHub without cloning the repository manually:
+```bash
+pip install git+https://github.com/PerfectWin7777/RockTranslate.git
+```
+
+---
+
+## 4. Visual Demonstration (Before & After)
+
+### Real-Time Application Lifecycle
+*The following animation demonstrates opening, rendering, and translating a multi-column paper dynamically:*
+
+<p align="center">
+  <img src=".github/assets/readme_animation.gif" width="800" alt="RockTranslate Application Demo" />
+</p>
+
+---
+
+### 🔬 1. English to Spanish (Elsevier Double-Column Layout)
+*Demonstrating perfect preservation of multi-column text flow, publisher headers, and author blocks.*
+
+![English to Spanish Comparison](.github/assets/readme_comparison_en_to_spa.png)
+
+*The original Elsevier double-column layout is fully retained with zero text-overlapping or margin drift.*
+
+---
+
+### 🧠 2. English to French (Attention Is All You Need — Abstract & Title)
+*Demonstrating precise preservation of scientific structures, titles, and mathematical equations.*
+
+![English to French Comparison](.github/assets/readme_comparison_en_to_fr.png)
+
+*Mathematical formulas, paragraph flows, and proper academic register remain completely intact.*
+
+---
+
+### 🌸 3. English to Japanese (Attention Is All You Need — Paragraph Flow)
+*Demonstrating robust handling of double-byte CJK characters without vertical line collapses or overlapping.*
+
+![English to Japanese Comparison](.github/assets/readme_comparison_en_to_jn.png)
+
+*Japanese Kanji and Kana characters are rendered cleanly with proportional horizontal scaling.*
+
+---
+
+### 🌸 4. English to German (Elsevier Double-Column Layout— Paragraph Flow and Table)
+*Demonstrating robust preservation of tables and math formulas in a double-column layout..*
+
+![English to German Comparison](.github/assets/readme_comparison_en_to_ge.png)
+
+*Clarity of paragraphs, tables and styles, preservation of mathematical formulas.*
+
+---
+
+## 5. The Three Versions
+
+RockTranslate provides three entry points to support any workflow:
+
+### A. Graphical User Interface (GUI)
+A responsive desktop application featuring:
+*   Synchronized dual-pane viewports (Original PDF vs. Live Translated HTML) [2].
+*   Real-time zoom sliders and page navigation.
+*   Visual shimmer skeleton loaders and real-time status bars [1, 2].
+
+### 📥 [Click here to download the standalone Windows Desktop GUI Installer (.exe)](https://github.com/PerfectWin7777/RockTranslate/releases/tag/v1.0.0-beta/RockTranslate_Setup_v1.0.0.exe)
+
+### B. Command-Line Interface (CLI)
+A lightweight execution engine that can be run globally from the terminal once installed [3].
+
+#### Usage Examples:
+1.  **Translate to French (default) using the default Gemini model:**
+    ```bash
+    rocktranslate article_scientifique.pdf -l French
+    ```
+2.  **Translate to Spanish and save to a custom output file:**
+    ```bash
+    rocktranslate paper.pdf -l Spanish -o report_es.pdf
+    ```
+3.  **Translate to German using OpenAI with an explicit API key:**
+    ```bash
+    rocktranslate document.pdf -m openai/gpt-4o-mini -k YOUR_OPENAI_KEY -l German
+    ```
+4.  **Run fully local translation using Ollama (no API key required):**
+    ```bash
+    rocktranslate document.pdf -m ollama/llama3 -l French
+    ```
+
+---
+
+### 💡 Dynamic Model Routing & Frontier Models Guidance
+
+#### 1. Model Naming Convention (LiteLLM Integration)
+RockTranslate inherits its entire model routing architecture directly from **LiteLLM**. All model identifiers passed through the `-m / --model` CLI flag (or through the API) must strictly follow the standard `provider/model_name` syntax. 
+
+Both the provider prefix and the model name must match the exact naming conventions defined in the [LiteLLM Supported Providers & Models Documentation](https://docs.litellm.ai/docs/providers).
+
+#### 2. Why Frontier Models are Essential for Perfect Visual Layouts
+While local or lightweight models function perfectly, we highly recommend using advanced **frontier models**—such as **Gemini 3.5 Flash**, **GPT 5.5**, **Claude 4.X**, **DeepSeek V4**, **Kimi K2.6**, or **GLM 5.5 ; Any other open-source LLM provider**—for complex scientific papers. 
+
+*   **Instruction-Following & Tag Integrity:** Frontier models possess superior reasoning capabilities. They strictly preserve nested XML style tags (like `<color_HEX>`) and structural JSON mapping arrays, allowing the renderer to position text segments with pixel-perfect accuracy.
+*   **Academic Register & Context:** They avoid literal, broken word-by-word translations of fragmented segments. Instead, they understand the global paragraph context, translating complex double-column academic layouts into natural scientific prose.
+
+
+### C. API Developer Library
+Integrate layout-preserved document translation directly into your Python scripts or data pipelines.
+
+#### Programmatic Integration Scenarios:
+```python
+import os
+from rocktranslate import RockTranslator
+
+# Ensure a sample file is present before initiating diagnostic runs
+sample_pdf = "article_scientifique.pdf"
+
+if not os.path.exists(sample_pdf):
+    print(f"Sample file '{sample_pdf}' not found. Please provide a valid PDF.")
+else:
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 1: Basic Translation (Using Google Gemini with environment key)
+    # ──────────────────────────────────────────────────────────────────────
+    # Automatically searches for GEMINI_API_KEY inside system environment variables.
+    # Uses the advanced Gemini 3.5 Flash model for superior layout preservation.
+    translator_gemini = RockTranslator(
+        model="gemini/gemini-3.5-flash",
+        target_lang="Spanish"
+    )
+    
+    # Executes translation, saving the file to '[article_scientifique]_translated.pdf'
+    success_gemini = translator_gemini.translate(input_pdf_path=sample_pdf)
+    print(f"Scenario 1 complete. Success: {success_gemini}")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 2: Custom Output Path and Language Customization
+    # ──────────────────────────────────────────────────────────────────────
+    translator_custom = RockTranslator(
+        model="gemini/gemini-3.5-flash",
+        target_lang="German"
+    )
+    
+    # Translates to German and writes output to a custom specified path
+    custom_output = "results/german_report.pdf"
+    os.makedirs("results", exist_ok=True)
+    
+    success_custom = translator_custom.translate(
+        input_pdf_path=sample_pdf,
+        output_pdf_path=custom_output
+    )
+    print(f"Scenario 2 complete. Translated PDF written to: {custom_output} (Success: {success_custom})")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 3: Frontier Provider (OpenAI GPT 5.5) with Explicit API Key
+    # ──────────────────────────────────────────────────────────────────────
+    # Explicit credentials pass overrides local environment configurations.
+    # We route the request using the exact LiteLLM naming convention (provider/model_name).
+    # Learn more at: https://docs.litellm.ai/docs/providers
+    translator_openai = RockTranslator(
+        model="openai/gpt-5.5",
+        api_key="sk-your-openai-api-key-here",  # Replace with a valid credentials key
+        target_lang="Italian",
+        temperature=0.3  # Lower temperature for more rigid, literal academic translation
+    )
+    
+    # success_openai = translator_openai.translate(input_pdf_path=sample_pdf)
+    print("Scenario 3 configured. (Run skipped to avoid credential errors.)")
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SCENARIO 4: Fully Local and Offline Translation (Using Ollama)
+    # ──────────────────────────────────────────────────────────────────────
+    # No API keys or remote servers required. Ensure Ollama is running on the host machine.
+    translator_local = RockTranslator(
+        model="ollama/llama3",
+        target_lang="French",
+        custom_base_url="http://localhost:11434"  # Default local Ollama gateway port
+    )
+    
+    # success_local = translator_local.translate(input_pdf_path=sample_pdf)
+    print("Scenario 4 configured for local offline execution.")
+```
+
+---
+
+## 6. Known Limitations & Roadmap (TODO)
+
+### Current Limitations:
+*   **The LaTeX FontForge Crash (Windows):** Older standalone versions of `pdf2htmlEX` on Windows occasionally experience segmentation faults or infinite loops when compiling complex, customized LaTeX mathematical fonts (Type-1 vector fonts) [2.2.6].
+    *   *Our Solution:* We have implemented a robust Windows crash preventer (`SetErrorMode`) and a strict 30-second subprocess timeout. If a compilation hangs, RockTranslate instantly terminates the process and fails gracefully in under 50ms without freezing the UI [1].
+
+### Roadmap & Future TODOs:
+*   [ ] **PyQt6 / QWebEngine Migration:** Migrate the Desktop GUI away from PyQt6 and heavy Chromium-based `QWebEngine` wrappers, transitioning towards a lightweight native webview (e.g., `pywebview`). This will reduce the compiled `.exe` bundle size from ~150MB down to under 20MB.
+*   [ ] **Automatic Fallback to Serverless Cloud Conversion:** Integrate an optional, free, or self-hosted serverless cloud rendering API (using the official Docker Linux image) to handle complex LaTeX papers without any local system limitations [1, 2].
+*   [ ] **Concurrent Batch Translation:** Implement parallel API calls (limited to 3 concurrent requests to respect free-tier quotas) to speed up translation times by 3x [1].
+
+---
+
+## 7. Contributing & Community Support
+
+We believe in making scientific literature universally accessible and welcome contributions from researchers, developers, and educators. Here is how you can help advance the project:
+
+*   **Core UI Refactoring:** Help us migrate from the resource-intensive PyQt6/QWebEngine setup to a lightweight `pywebview` client.
+*   **Bug Reports & Edge Cases:** Found a PDF with highly complex LaTeX layout issues? Open an issue and upload the file (or a sample page) so we can optimize our BeautifulSoup parser rules.
+*   **Translation & Localization:** Contribute internationalization files (`.qm`/`.ts` translations) to make the user interface available in more languages.
+*   **Prompt Optimization:** Help us refine the instructions in `prompts.py` to further improve terminology preservation and tag alignment across different languages.
+
+To contribute, please fork the repository, make your changes in a dedicated branch, and submit a pull request. For major architectural modifications, feel free to open an issue first to discuss your ideas with the core maintainers.
+
+---
+
+## 8. Acknowledgements & Credits
+
+RockTranslate stands on the shoulders of giants. We would like to express our deepest gratitude to the open-source projects that made this tool possible:
+*   **pdf2htmlEX:** The geometric engine used to compile PDF structures into HTML [2.2.1] ([GitHub](https://github.com/pdf2htmlEX/pdf2htmlEX)).
+*   **Poppler & FontForge:** The underlying vector engines driving pdf2htmlEX [3.2.4] ([Poppler Website](https://poppler.freedesktop.org/) | [FontForge Website](https://fontforge.org/)).
+*   **LiteLLM:** The multi-provider AI routing wrapper [2.3.1] ([Official Documentation](https://docs.litellm.ai/)).
+*   **BeautifulSoup4 & lxml:** Driving high-speed, programmatic DOM analysis ([BeautifulSoup Documentation](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) | [lxml Website](https://lxml.de/)).