RockTranslate

High-Fidelity AI Layout-Preserved PDF Translator

📥 Click here to download the standalone Windows Desktop GUI Installer v2.0.5 (.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), disrupting complex formulas, double-column structures, and tabular alignments [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].
• Paragraph-Level Translation with Justified Reflow (new in 2.0.5): Lines are regrouped into real paragraphs, translated as whole sentences, then reflowed into the original line boxes with one uniform scale per paragraph — justified when the source was justified, like professional document translators.
• Protected PDFs: Copy-restricted publisher PDFs open normally; password-protected PDFs prompt for their password (kept in memory only).
• 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 & Economical: Concurrent LLM requests (4 by default), hidden-reasoning disabled where supported (≈5× faster, ≈4× cheaper on DeepSeek), and a translation cache: nothing is ever paid twice for the same text.
• Transparent Usage: Live elapsed time, remaining time, tokens and estimated cost during each run, plus cumulative statistics per model.
• Original Text on Hover: Hover a translated paragraph to read the original in a bubble (toggle in Settings; Ctrl + hover always works).
• Structured Extraction & Aligned Translation (new in 2.0.5): rocktranslate.extract() turns a PDF into typed, positioned elements (sections, paragraphs, tables cell by cell, captions, formulas…) as JSON, Markdown or RAG chunks — and rocktranslate.translate() attaches each element's translation. Search a passage and highlight it in the original PDF. See real outputs →
• Native pdf2htmlEX 0.18.8 on Windows (new in 2.0.5): The first public native 64-bit Windows build of pdf2htmlEX 0.18.8 — built by our CI from source (build recipe, engine release) — 1.4–2.5× faster than the old 32-bit 0.14.6 and free of its 2 GB memory limit.
• Synchronized Side-by-Side View: Original PDF on the left; on the right, the reconstructed layout, prepared in the background as soon as the PDF opens (no AI, no cost), so translation starts instantly. Same zoom and synchronized scrolling; a collapsible progress panel shows pages, segments, time, tokens and cost.
• Exact Layout Measurement with Your Browser: Paragraph geometry is measured with the installed Edge or Chrome (driven through the DevTools protocol), or with a small headless engine fetched in the background — nothing to install by hand.
• Light & Dark Themes: A native-feeling interface (light, dark or follow the system) with a unified Settings window (Ctrl/⌘+,).
• 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)

RockTranslate is officially published on PyPI. You can install the core lightweight library (CLI & API only) or include full desktop GUI support:

For CLI & Programmatic API only (Lightweight, No GUI):

pip install rocktranslate

For the full Desktop Graphical User Interface (GUI):

pip install "rocktranslate[gui]"

B. Development Installation (via Git)

For the most up-to-date features, or to run the application directly from source:

# 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:

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:

🔬 1. English to Spanish (Elsevier Double-Column Layout)

Demonstrating perfect preservation of multi-column text flow, publisher headers, and author blocks.

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.

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.

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..

Clarity of paragraphs, tables and styles, preservation of mathematical formulas.

5. The Four Ways to Use RockTranslate

RockTranslate provides four entry points to support any workflow: the desktop GUI, the CLI, the Python API, and structured extraction (§5.D):

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 v2.0.5 (.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 with the model saved in the GUI (or the default):

   rocktranslate paper.pdf -l French
   

2. Translate only some pages (only those pages are converted):

   rocktranslate paper.pdf -l Spanish --pages "1-3, 7" -o paper_es.pdf
   

3. Use DeepSeek, OpenAI, Gemini… (LiteLLM model routes):

   export DEEPSEEK_API_KEY=sk-...
   rocktranslate paper.pdf -m deepseek/deepseek-flash -l German --parallel 6
   

4. Fully local translation with Ollama (no API key):

   rocktranslate paper.pdf -m ollama/llama4 --base-url http://localhost:11434
   

5. Password-protected PDF:

   rocktranslate locked.pdf --password "secret"
   

6. Check the environment (pdf2htmlEX, PDF engine, API keys):

   rocktranslate doctor
   

Each run ends with a summary (segments, time, tokens, estimated cost). Exit code 0 = success, 2 = partial result (some batches failed, the PDF was still produced), 1 = failure.

No browser to install manually: RockTranslate prints PDFs with an installed Chrome / Edge / Chromium / Brave, and otherwise downloads a pinned chrome-headless-shell into your user folder (never into site-packages). On Windows, the pdf2htmlEX engine (native x64 build of 0.18.8) is downloaded on first use when it is not bundled. On Linux, the official pdf2htmlEX AppImage is extracted automatically — no FUSE required (Docker, WSL, Ubuntu 22.04+). Override with ROCKTRANSLATE_BROWSER=/path/to/chrome if needed.

💡 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.

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.8 Flash, GPT-5.6 Terra, Claude 5 Sonnet, DeepSeek V4, Llama 4, or Kimi K2.6—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:

from rocktranslate import RockTranslator

rt = RockTranslator(
    model="deepseek/deepseek-flash",   # any LiteLLM route: gemini/..., openai/..., ollama/...
    target_lang="French",              # API key read from DEEPSEEK_API_KEY (or pass api_key=...)
    parallel=4,                        # concurrent requests
    temperature=0.3,                   # faithful translation
)

report = rt.translate_document("paper.pdf", "paper_fr.pdf", pages="1-5")
print(report.success, report.output_path)
print(f"{report.segments_translated} segments in {report.seconds:.0f}s, "
      f"{report.prompt_tokens + report.completion_tokens} tokens, ~${report.cost_usd:.3f}")

# Backward-compatible boolean API
ok = rt.translate("paper.pdf")

The library never reads hidden GUI settings for what you pass explicitly (model, key, temperature, retries), and caches translations by document content: re-running the same document is free.

D. Structured Extraction & Aligned Translation (new in 2.0.5)

RockTranslate also turns a PDF into typed, positioned elements — the schema popularized by Unstructured — and, unlike layout-only extractors, every element can carry its aligned translation. Local and free for extraction (no API key); translation uses your own LLM key, or a local Ollama model.

🔎 See it on real papers (outputs below are unedited)

1 · Tables rebuilt cell by cell. Input: Table 4 of an open-access geology paper (Wabo Defo et al., Geological Magazine, 2026, CC BY 4.0).

rocktranslate extract paper.pdf -p 11 -f md → Markdown (first rows):

| 1 | 1.02 | 0.02 | 1.07 | 12.74 | 0.20 | 1.90 | 0.44 | 48.17 | 0.39 | 0.31 |
| 2 | 0.80 | 0.01 | 1.33 | 2.42 | 0.20 | 1.79 | 0.29 | −21.74 | 0.18 | 0.26 |
| 3 | 0.44 | 0.01 | 5.63 | 3.88 | 0.39 | 2.37 | 0.47 | 9.95 | 0.25 | 0.06 |
| 4 | 0.72 | 0.02 | 1.75 | 22.14 | 0.33 | 0.37 | 0.18 | 66.71 | 0.53 | 0.23 |
| 5 | 0.77 | 0.01 | 1.75 | 26.98 | 0.34 | 1.27 | 0.38 | 12.88 | 0.20 | 0.09 |

…all 45 rows, every value in its column. The same table in JSON (-f json), with its page and its box in PDF points:

{
  "type": "Table",
  "element_id": "48bf2b723bd45202892c544214d92c4c",
  "text": "Geomorphic indices | Parameters of the normalised profiles\nRe | Rr | Bs | A\nTTSF | Vf | HI...",
  "metadata": {
    "page_number": 11,
    "coordinates": { "points": [[50.0, 97.12], [50.0, 747.27], [546.89, 747.27], [546.89, 97.12]],
                     "system": "PDFPoints", "origin": "top-left" },
    "text_as_html": "<table><tr><td>1</td><td>1.02</td>…</table>"
  }
}

2 · The document's real structure. Input: page 1 of Attention Is All You Need (arXiv:1706.03762).

Markdown outline produced by rocktranslate extract (headings with their real depth, numbering kept):

# Attention Is All You Need
## Abstract
## 1 Introduction
## 2 Background
## 3 Model Architecture
### 3.1 Encoder and Decoder Stacks
### 3.2 Attention
#### 3.2.1 Scaled Dot-Product Attention
#### 3.2.2 Multi-Head Attention
### 3.3 Position-wise Feed-Forward Networks
## 4 Why Self-Attention
…

Author marks stay attached (Ashish Vaswani<sup>∗</sup>), footnotes are typed Footnote, the rotated arXiv stamp is read as one Header (arXiv:1706.03762v7 [cs.CL] 2 Aug 2023), and words drawn inside figures are kept apart as FigureText.

3 · Bilingual, aligned paragraph by paragraph. rocktranslate paper.pdf -l French -p 1 -f md --bilingual:

## Abstract

> Résumé

The dominant sequence transduction models are based on complex recurrent or convolutional
neural networks that include an encoder and a decoder. […]

> Les modèles dominants de transduction de séquences reposent sur des réseaux neuronaux
> récurrents ou convolutifs complexes comprenant un encodeur et un décodeur. […]

Unchanged text (names, e-mails, codes) is not repeated; tables are translated cell by cell (table_translation).

4 · Find a passage, see it in the original PDF. doc.search() looks into the original and the translation; doc.highlight() frames the hits at their exact position in a copy of the source PDF:

doc = rocktranslate.extract("attention.pdf")
hits = doc.search("multi-head attention")          # 10 elements, pages 1-5
doc.highlight(hits, "attention.pdf", "attention_hits.pdf")

5 · RAG-ready chunks. doc.chunks(1500) never mixes two sections nor cuts an element, and keeps where every piece comes from:

{
  "text": "Recurrent neural networks, long short-term memory [13] and gated recurrent [7] …",
  "section": "1 Introduction",
  "pages": [2],
  "element_ids": ["b47cb8d9461009d29cd4b9a1b623f9c8", "74fe378b8679534ef389b177167f53f2"],
  "boxes": [[2, [108.0, 85.56, 504.36, 150.28]], [2, [108.0, 145.58, 504.47, 243.03]]]
}

🐍 Python API

import rocktranslate

# Structure only: local, free, no API key
doc = rocktranslate.extract("paper.pdf")              # optional: pages="1-5", password="..."
print(doc)            # <Document 'paper.pdf': 531 elements (135 NarrativeText, 31 Section, 4 Table, ...)>
doc.to_markdown("paper.md")
doc.to_json("paper.json")                             # our element types
doc.to_json("paper.unstructured.json", unstructured=True)   # Unstructured's category names
chunks = doc.chunks(max_characters=1500)
for table in doc.tables:
    print(table.table[:3])                            # rows x cells; table.html for HTML

# Translation: the same elements, each with its translation (+ the translated PDF)
doc = rocktranslate.translate("paper.pdf", lang="German", pages="1-2")
doc.to_markdown("paper.de.md", bilingual=True)
doc.search("Aufmerksamkeit")                          # search in German, get the English source too
print(doc.report.cost_usd, doc.output_pdf)

⌨️ CLI

rocktranslate extract paper.pdf -f json,md,chunks             # structure only
rocktranslate paper.pdf -l German -f pdf,json,md --bilingual  # translated PDF + aligned JSON/Markdown

📊 Measured against Unstructured

Same PDFs, Unstructured 0.18 with strategy="fast" (its pdfminer-based mode that needs no ML model):

Honest limits: displayed equations are only partly reassembled; table header rows spanning several levels can be split; tables whose rows are drawn as one text run (e.g. some LaTeX tables) are not split into cells yet; scanned PDFs (no text layer) would need OCR; PDF input only. Unstructured's heavier hi_res mode (ML layout models) was not part of this comparison.

---|---| | Title / Section | document title; numbered or typographic headings, with category_depth (3.2.1 → 2) | | NarrativeText, ListItem, Reference | paragraphs (regrouped across lines), list items, bibliography entries | | Table | rows × cells (table), text_as_html, translated cell by cell | | FigureCaption, TableCaption, Formula, Footnote | captions, displayed equations, notes | | Header, Footer, FigureText | page furniture and labels inside figures (kept in JSON, left out of Markdown/chunks) |

Measured on the same PDFs (Unstructured 0.18 strategy="fast", the pdfminer-based mode that needs no ML model):

Limits: scanned PDFs (no text layer) need OCR, which RockTranslate does not do; only PDF input.

6. Known Limitations & Roadmap (TODO)

Current Limitations:

• Fonts embedded as subsets: publisher PDFs only embed the glyphs they use. Translated text needing other glyphs (accents, CJK) falls back to a system font for those characters, which can look slightly different.
• Run-in headings and complex inline math: a line starting with a bold run-in heading ("Residual Dropout We apply…") or packed with inline formulas is translated line by line instead of as part of its paragraph.
• Longer target languages shrink the text of a paragraph uniformly to keep it inside its original box (as other layout-preserving translators do).
• Scanned PDFs (images only) are not supported yet (no OCR).
• pdf2htmlEX on Windows is our own native x64 build of pdf2htmlEX 0.18.8 (recipe in tools/pdf2htmlex-windows/), bundled by the installer and downloaded on first use otherwise (~16 MB). If a conversion stops making progress, RockTranslate stops the process and reports the reason.

Roadmap:

• Structured extraction (rocktranslate.extract, to_json, to_markdown, chunks, search, highlight) — see §5.D.
• Bilingual export of every translated element (JSON, bilingual Markdown).
• TMX export (translation-memory format for CAT tools).
• Tables drawn as single text runs split into cells; multi-level table headers.
• Scanned PDF support through a local OCR fallback.
• Sliced parallel conversion of very large documents in the GUI (the CLI already converts only the requested pages; merger prototyped in core/html_merger.py).

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:

• UI/UX Polish: Help us improve the pywebview interface — modal dialogs, theming, accessibility, and layout refinements.
• 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 dictionaries (in src/rocktranslate/assets/ui/js/i18n.js) 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).
• Poppler & FontForge: The underlying vector engines driving pdf2htmlEX [3.2.4] (Poppler Website | FontForge Website).
• LiteLLM: The multi-provider AI routing wrapper [2.3.1] (Official Documentation).
• BeautifulSoup4 & lxml: Driving high-speed, programmatic DOM analysis (BeautifulSoup Documentation | lxml Website).