Ozan Özdil
EN

Machine translation from Turkish (Cloudflare Workers AI), not reviewed by the author. Read the Turkish original

← Posts

PolyCodex: An Open-Source PDF Translator with 1:1 Layout and Visual Inviolability, with a 5000-Page Capacity

Score —

A next-generation codex translation engine built on Rust and Quickshell that extracts text blocks from the PDF content stream with surgical precision, preserves images and tables down to their pixels, prevents overflow with Tz microtypographic horizontal compression, and runs entirely offline with Ollama local artificial intelligence.

· 6 min read
Contents

Summary: PolyCodex is an open-source tool that translates PDFs without disrupting page layout or images. The text explains its approach of changing only text blocks, fitting expanded translated text via Tz horizontal scaling, its streaming memory structure for documents exceeding 5000 pages, offline translation with Ollama, its Quickshell interface and CLI mode, and four installation methods.

Anyone working in academic research, extensive medical literature, military technical manuals, and engineering documentation running to thousands of pages faces a common and chronic dilemma: the impossibility of PDF translation.

When traditional tools (Google Translate's PDF module, Adobe Acrobat, Calibre, or common OCR software) try to transfer a document into another language, disaster scenarios become inevitable: multi-column pages get jumbled together, technical drawings and vector diagrams fly off the page, tables are fragmented, footnotes get lodged in the middle of the main text, and ultimately the process is interrupted by arbitrary server limits such as 10 MB or 300 pages.

Even worse, the uncontrolled transfer of corporate documents, patent drafts, and confidential research to third-party cloud servers is an unacceptable vulnerability in terms of data sovereignty and cybersecurity.

PolyCodex, which I developed to solve these structural problems at their root, keep layout and images untouched, and smoothly convert even 5000+ page codexes entirely on local hardware, is now released as an independent open-source project.

Core Philosophy: "Layout Is Sacred, Visuals Are Untouchable"

A PDF (ISO 32000) does not consist of fluid text paragraphs like a Word document. A PDF is a digital printing canvas in which every letter, line, and image is defined by absolute positions on a two-dimensional coordinate plane (x, y).

The main reason existing translation tools fail is that they convert the PDF into a text-based document and then try to re-render it. This approach destroys the entire typographic geometry of the original document.

PolyCodex adopts a different paradigm: Surgical Content Stream Manipulation.

  • PolyCodex Content Stream Parsing Pipeline: lopdf & Rust Engine

1. TEXT BLOCKS (BT / ET)

Only the Tj and TJ operators between BT (Begin Text) and ET (End Text) are read. Matrix positions (Tm) are preserved, and the texts are sent to the translation pool.

2. VISUAL UNTOUCHABILITY (Do)

Do (XObject invocation) commands, vector paths (re, m, l, c, f, S), and color states are preserved down to their pixels. Not a single byte is deleted.

3. Tz MICROTYPOGRAPHY

Dynamic horizontal scaling (Tz) is calculated for the expanding target-language text. The original bounding box is preserved to the millimeter.

Microtypography and the Tz Horizontal Scaling Solution

The character densities and word lengths of different languages differ radically. For example, when an English technical document is translated into Turkish or German, the text volume expands by an average of 25% to 35%.

Faced with this expansion, traditional software either clips the text and makes it unreadable or overflows it onto the next image or table, disrupting the page layout.

PolyCodex solves this problem with Tz (Horizontal Scaling), a native operator of the PDF standard:

  1. The width of the translated sentence in the target language (W_target) is compared with the bounding box width of the original sentence (W_original).
  2. If W_target > W_original, a dynamic compression factor is calculated without changing the font size or line height: Tz = max(75.0, (W_original / W_target) * 100.0)
  3. The calculated operator is injected directly into the PDF content stream (for example, 88.5 Tz). Thus the letters draw closer together with microtypographic elegance, page boundaries are not exceeded, and the adjacent diagram or schematic never shifts from its place.

5000+ Page Capacity and Streaming Memory Architecture

Many PDF tools on the market are written with Python or Node.js/Electron libraries. These tools try to load the entire document tree into RAM at once; after 300-500 pages, memory consumption skyrockets to 8-16 GB levels, and the system is forcibly terminated by the operating system with the OOM Killer (Out Of Memory).

PolyCodex's core engine is built with Rust:

  • Page-Based Streaming Architecture: Document pages are processed one by one, temporary buffers are cleared, and output is safely written to the file.
  • Constant Memory Footprint: Whether it is a 10-page article or a 5,200-page pharmacology handbook, the PolyCodex engine's RAM consumption remains constant in the 150 MB to 250 MB range.
  • DoS and Resource Consumption Shield: To prevent memory exhaustion and corrupted/malicious PDF attacks, a strict 2 GiB ceiling limit check is enforced. Size checks are verified with checked_add and safe boundary guards.
  • Hardened File Permissions: The temporary and final files produced are created with 0600 permissions (read/write) accessible only to the file owner; symbolic links (symlinks) are strictly rejected.

Data Sovereignty: 100% Offline Translation with Local Ollama

PolyCodex gives the user complete independence in their choice of translation engine:

                  +-----------------------------------+
                  |             POLYCODEX             |
                  |     (Rust Core / Quickshell)      |
                  +-----------------+-----------------+
                                    |
          +-------------------------+-------------------------+
          |                         |                         |
          v                         v                         v
+-------------------+     +-------------------+     +-------------------+
|    YEREL OLLAMA   |     |  LIBRETRANSLATE   |     |    MOCK / TEST    |
| (Llama 3 / Qwen)  |     |   (Self-Hosted)   |     | (Yerel Simülatör) |
|  TAM ÇEVRİMDIŞI   |     |   AÇIK KAYNAK     |     |   SIFIR DIŞ AĞ    |
+-------------------+     +-------------------+     +-------------------+
  1. Ollama Integration (Llama 3.2, Qwen 2.5, DeepSeek, Mistral): Local AI translation that requires no network connection and runs on the power of your hardware even in air-gapped environments and during internet outages. No piece of text ever leaves your computer.
  2. Open Source LibreTranslate Support: Full compatibility with open source translation APIs hosted on your own server or local network.
  3. Mock Mode: Instant translation simulation and layout verification in test environments without a network or LLM resource.

Quickshell and the Modern Wayland User Experience

Instead of clunky traditional interfaces with a heavy dependency burden, PolyCodex uses Quickshell (Qt 6 / QML) technology, the flagship of the Omarchy desktop:

  • GPU-Accelerated Fluid Interface: 60+ FPS smooth animations, an OLED-friendly pure black and graphite dark theme palette.
  • System Font Standard: The entire typographic hierarchy of the interface is shaped by the JetBrainsMono Nerd Font standard for clarity and readability.
  • Live Progress and Page Tracking: In very large documents, the current page, remaining time and instant translation steps are reported to the user with millisecond precision.
  • Single-Instance Lock Shield: To prevent the application from being launched multiple times at once and consuming system resources, the $XDG_RUNTIME_DIR/polycodex.lock file lock mechanism has been enabled.

Direct Automation via the Terminal (CLI Mode)

# Tek komutla PDF çevirisi (Kaynak: Otomatik, Hedef: Türkçe, Sağlayıcı: Ollama)
polycodex --input "/path/to/quantum_physics.pdf" \
          --output "/path/to/kuantum_fizigi.pdf" \
          --target "tr" \
          --provider "ollama"

# 5000 sayfalık teknik el kitabını yerel LibreTranslate ile dönüştürme
polycodex -i handbook.pdf -o el_kitabi.pdf -t tr -p libretranslate

Installation and Distribution Channels

PolyCodex is packaged to run effortlessly on Arch Linux, Fedora, Ubuntu, Debian and all other modern Linux distributions.

1. Universal Single-Command Installation Script

The official installation script that downloads and configures the binary best suited to your system:

curl -sSL https://raw.githubusercontent.com/ozdil/polycodex/main/install.sh | bash

2. Arch Linux / AUR (Arch User Repository)

The official AUR package for Arch Linux and Omarchy users:

yay -S polycodex-bin
# veya kaynak koddan derlemek için:
yay -S polycodex

3. Universal Flatpak / Flathub Distribution

With the package (org.ozdil.PolyCodex) currently in Flathub's official review process, one-click sandbox-protected installation on all Linux platforms:

flatpak install flathub org.ozdil.PolyCodex

4. GitHub Standalone Binary Assets (Releases)

For those who want to run it directly without installing any dependencies, compiled x86_64 binaries are available on the GitHub Releases page:

My reading

A very large portion of the scientific and technical knowledge humanity has produced is trapped in foreign languages and behind closed PDF formats. It is unacceptable that researchers, students and engineers who want to access this knowledge are condemned to translations with broken layouts, erased diagrams or cropped pages.

PolyCodex both protects privacy by using the full power of local hardware and shows absolute respect for the document's original aesthetics and typography.

All its source code, contribution guide and documentation are open to the community on GitHub.

Sources