OPEN PDF Translate

An Obsidian plugin that translates PDF documents directly inside your vault. Translated text is displayed as a transparent overlay on top of the original PDF, or written to a separate Markdown note for scanned documents.

Requirements

The Internal layout engine works without Python — it reads the text layer already rendered by Obsidian's PDF viewer. Use Python for better layout accuracy or for background/headless translation.

Quick Start

1. Install the plugin and enable it in Settings → Community Plugins.
2. Open Settings → OpenRouter PDF Translator.
3. Choose a Provider (e.g. OpenRouter) and enter your API key.
4. Click Refresh next to the model dropdown and select a model.
5. Set Source Language and Target Language.
6. Open any PDF in Obsidian.
7. Run the command "Translate and add overlay to current PDF page" (or assign a hotkey).

The translated text appears as a coloured overlay on top of the original. Scroll to another page and run the command again, or use "Translate multiple pages…" to process a range at once.

How It Works

Overlay Mode (for PDFs with a text layer)

1. The plugin extracts text blocks and their positions from the current PDF page.
2. Each block's text is sent to the configured AI provider for translation.
3. The translated text is rendered as an absolutely-positioned HTML overlay on top of the PDF viewer — the original PDF is not modified.
4. Overlay data is saved to a companion .translations.md file in your vault. The next time you open the PDF, overlays load instantly without re-translating.

OCR Mode (for scanned / image PDFs)

For PDFs with no text layer, a different pipeline is used. See OCR (Ai Vision)

Layout Engines

Choose the engine in Settings → Layout Engine.

Internal (default)

Reads the text layer that Obsidian's built-in PDF.js renderer produces. Works out of the box with no extra dependencies.

• Best for: PDFs with clean text layers (digital-born PDFs).
• Limitation: Cannot run in the background; requires the PDF to be open in a tab.

External Python (PyMuPDF)

Runs layout_engine.py (a bundled script) using your local Python installation. PyMuPDF reads the PDF directly from disk without the browser renderer.

• Best for: Better layout accuracy, multi-column documents, and background translation (Folder Watcher).
• Requirement: Python 3.8+ and pip install pymupdf.

Setup:

1. Go to Settings → Layout Engine → Bundled Python Scripts and click Install / Update Scripts. The scripts are written into the plugin folder and the paths are filled in automatically.
2. Set the path to your Python interpreter (e.g. /usr/bin/python3).
3. Switch the Layout Engine dropdown to External Python script (PyMuPDF).

Note: The Python engine is the only one that supports headless background translation via the Folder Watcher, because it reads the file from disk rather than from the browser's DOM.

Providers

Go to Settings → Translation Provider to configure which AI service handles translation.

Model lists are fetched live from each provider. Click Refresh (⟳) after entering your key to populate the dropdown. If your model isn't in the list, type its exact ID in the Model ID (manual) field — this always takes precedence.

Temperature

Controls how deterministic the output is. 0.0 = always picks the highest-probability token (best for translation consistency). 1.0 = more creative/varied. Default is 0.3.

OCR (AI Vision)

For scanned PDFs or image-only PDFs that have no text layer, use the OCR subsystem. It is independent from the Layout Engine — you can keep Python for normal PDFs and run OCR on scans at the same time.

How OCR works

1. Each page is rasterized to a high-resolution image (configurable scale, default 2×).
2. The image is sent to a vision-capable AI model (your configured OCR provider) with a transcription prompt.
3. The returned text is translated via the main translation pipeline.
4. The result is written to a Markdown note in your vault, with one section per page. The note is updated incrementally — each page is written as it completes, so cancelling mid-run still leaves you with partial results.

OCR Provider

The OCR model can be different from the translation model. Configure it in Settings → OCR (AI Vision). Supported providers: OpenRouter, OpenAI, Google Gemini, Ollama, Custom.

Output format

Each recognized note has this structure:

---
pdf-source: "[[path/to/document.pdf]]"
ocr-model: google/gemini-flash-1.5
target-language: Russian
generated: 2026-06-01T12:00:00Z
---

# document — translation

<!-- ocr-page:1 -->
## Page 1
[[path/to/document.pdf#page=1|→ page 1]]

Translated text of page 1…

<!-- ocr-page:2 -->
## Page 2
…

Running OCR on a page that already exists in the note overwrites only that page's section — the rest of the note is untouched. Pages always stay in order regardless of what order they were recognized.

Running OCR

• One page: Command "OCR: recognize current page to translated note" — processes whatever page is currently visible.
• Page range: Command "OCR: recognize PDF to translated note (choose pages)…" — opens a dialog to select a start and end page, with a real-time progress indicator and a Cancel button.

Tip: For the best recognition quality, set Image Scale to 2 or higher in OCR settings, and choose a vision model with strong OCR ability

Background Translation (Folder Watcher)

The Folder Watcher monitors a vault folder for new PDFs and queues them for background translation. Requires the Python layout engine — Python is the only engine that can extract text from a file without opening it in a tab.

The watcher never starts a translation automatically. Detection only queues files; you trigger translation manually from the queue.

Setup

1. Go to Settings → Folder Watcher.
2. Enable the watcher and select the folder to watch (non-recursive — only immediate children of that folder are detected).
3. The watcher starts when the plugin loads and stops when you disable it or close Obsidian.

Queue

Open the queue with the command "Background translation: open watched-folder queue" or the button in Settings.

Click Translate on a single item or Run all pending to process the whole queue sequentially.

Scan folder now checks the watched folder for existing PDFs that don't yet have a translation file and adds them to the queue.

What background translation produces

The output is the same as a normal Python overlay translation: a .translations.md file saved according to your storage location setting. When you open the PDF, overlays load from this file instantly without re-translating.

Commands Reference

Open the command palette (Ctrl/Cmd + P) and search for any of these commands.

Overlay Translation

OCR

Background Translation

Maintenance

Layout & Debug

Settings Reference

Translation Provider

Configure the AI model used for translation text. Each provider has its own model list and API key field.

• Model dropdown: populated from the provider's API. If your model isn't listed, type the exact ID in Model ID (manual).
• Temperature: 0.0–1.0. Default 0.3. Lower = more consistent terminology. Higher = more varied phrasing.
• Enable Reasoning: For models like DeepSeek R1, o1, QwQ — enables extended thinking mode.

General Settings

Folder Watcher

Translation Prompts

Read the help text in the settings panel before editing prompts — it explains placeholders and the rules that keep batch translation aligned.

In short:

• Batch prompt handles full pages at once. It receives numbered [#1], [#2]… segments and must return them with the same tags. Do not remove {lineCount} or the [#N] instructions.
• Single sentence prompt handles one fragment at a time and has no numbering requirement.
• Special template (optional): for models like Gemma that expect a single combined prompt with {TEXT}. Overrides both prompts above when enabled.

Layout Engine

OCR (AI Vision)

PDF Export

The export renders a white background behind each translated block and uses each block's own text color. Additional rendering options (font scale, color per block) are set per-export in the export dialog.

Translation Files

Each translated PDF gets a companion file: <pdfname>.translations.md (or <pdfname>.translated.md for OCR notes). These files live next to the PDF by default, or in the folder you specify in Translation Storage Location.

Overlay data format (.translations.md)

---
pdf-source: "[[path/to/document.pdf]]"
timestamp: 2026-06-01T12:00:00Z
format-version: 3
---

The rest of the file contains serialized overlay position data. Do not edit this file manually unless you know what you're doing — it will be overwritten on the next translation.

Linking

The pdf-source field uses a wiki-link so Obsidian graph view shows the relationship between the PDF and its translation file. If you move or rename a PDF, run "Repair translation links" to update the link.

PDF Export

Export PDF with translations permanently embeds the overlay text into a new PDF file using PyMuPDF. The original PDF is not modified — a new file is created.

Requirements: Python + pip install pymupdf.

Setup:

1. Install the bundled scripts (Settings → Layout Engine → Install / Update Scripts).
2. The PDF export script path is set automatically.
3. Run "Export PDF with translations" from the command palette.

Troubleshooting

Overlays don't appear after opening a PDF

1. Run "Rebuild PDF-to-translation file map". This happens automatically on startup, but a vault rescan fixes stale links after moving files.
2. Check that the .translations.md file exists and its pdf-source field points to the correct PDF path. If the PDF has an apostrophe in its filename, run "Repair translation links".

Translation produces garbled or misaligned text

• The model returned segments out of order or dropped some [#N] tags. Lower Max Batch Input Length (try 2000–3000 chars) to reduce the chance of truncation.
• Enable Debug Mode to see the exact prompt and response in the developer console (Ctrl/Cmd + Shift + I).
• If using a custom model, check that it actually supports chat completions and returns plain text.

Python engine doesn't work

1. Verify the interpreter path: open a terminal and run python3 --version.
2. Verify PyMuPDF: python3 -c "import fitz; print(fitz.__version__)".
3. Use Settings → Layout Engine → Test Setup to run a diagnostic check.
4. On Windows, use the full path to python.exe (e.g. C:\Python311\python.exe).

OCR quality is poor

• Increase Image Scale to 3 or 4 (higher = better quality, larger API payload).
• Use a vision model known for strong OCR (GPT-4o, Gemini 1.5 Pro, or a fine-tuned local model).
• Edit the Transcription Prompt to mention the document language or domain (e.g. "This is a medical document in Russian").

Rate limit errors (429)

• Increase Delay Between Requests in General Settings (try 500–1000 ms).
• Switch to batch mode (enabled by default) — it sends fewer, larger requests.
• Upgrade to a paid API tier or switch providers.

Background translation skips files

• Make sure the Layout Engine is set to Python — background translation requires PyMuPDF and will not run on Internal or OCR engines.
• Check the Python interpreter and script paths are correct.
• Open the watcher queue (command: "Background translation: open watched-folder queue") and read the error message next to the failed item.

Languages

The plugin UI automatically switches between English and Russian based on Obsidian's language setting. To change Obsidian's language: Settings → General → Language.

All other languages currently display in English. To add a new language, edit i18n.ts and add a new locale object following the existing EN and RU pattern.

Privacy

All PDF text and translation requests go directly from your machine to the API provider you configure. No data passes through any intermediate server operated by this plugin. When using Ollama, everything stays entirely local.

Credits

Built on Obsidian, PDF.js (bundled in Obsidian), and optionally PyMuPDF. Translation is powered by whichever AI provider you choose.