Verbilo — Portable

Translate DOCX, XLSX and PDF into languages while preserving layout, styles, and images.

---

How it works (high level)

• Converts document content into translation units (runs, spans, rows, paragraphs)
• Sends grouped units in batches to translation backends with resilient HTTP retries and sub-batch fallbacks for large requests.
• Uses API-aware inline tagging where supported to preserve run/span formatting across the round-trip.
• Reconstructs translated text back into the original document structure, applying formatting where feasible.

Feature Highlights

• Multiple translation engines: Google Translate (free), Google Cloud Translation API, Baidu, Azure, DeepL.
• Proxy & resilience: All engines use a resilient HTTP session with retries, backoff, timeouts, and optional HTTPS/HTTP proxy.
• Selective Translation: Translate only text in a specified source language (or use auto).
• Formatting Preserved: DOCX run-level, XLSX cell and in-place PDF Editing are preserved.
• Multi-Engine Detection: Lingua, FastText — choose your preferred engine. (quality / speed)
• Batching for Efficiency: Segments are batched to reduce API calls and avoid rate limits.
• Semantic Translation: Uses a dual-model approach - a translation model plus a smaller companion advisor that classifies blocks before LLM calls, with pre-routing and batch grouping to minimise latency.
• GUI Language: Interface available in English and Chinese Simplified (ZH-Hans), selectable in Settings.

Known limitations

• Tag survival is API-dependent; inline tag preservation is not guaranteed on every backend.
• Z-order guard is conservative: it avoids translating text entirely covered by opaque graphics rather than rewriting PDF content streams to change stacking order.
• Very-short CJK tokens (1–2 characters) can behave inconsistently across translation APIs—prefer explicit source_lang to ensure correct source language.
• Extremely complex layouts (heavy overlays, rotated text, or nonstandard encodings) can still produce visual artifacts - manual verification recommended for critical documents.
• Chinese→English can be challenging for complex documents because Chinese often uses topic-prominent constructions while English is subject-prominent.

Quick Start — For Developers

1. Install core dependencies:

pip install -r requirements.txt

2. Launch the GUI:

cd src
python -m launch

3. If using GUI, and errors for UI helpers or icons appear:

pip install customtkinter
pip install pytablericons Pillow

---

GUI translation engines & network settings

In the GUI sidebar you can choose the translation engine:

• Google Translate (free) ~ default, no API key required.
• Google Cloud Translation API ~ requires: API key for v2, Project ID & Account Credentials for v3.
• Baidu Translate ~ requires Baidu App ID and App Key.
• Microsoft Azure Translator ~ requires a Subscription Key and Region.
• DeepL ~ requires a DeepL API key (Free or Pro).
• Local (offline) ~ free and unlimited use, requires download of each language model source+target
• Ollama (local LLM) ~ free and unlimited use, requires [Ollama] running locally.

Settings → Network & API keys to configure

If any API method is selected without credentials, the GUI will show a warning instead of starting the job.

Local AI translation via Ollama (offline, no API key)

Verbilo can use local Ollama models as the translation engine for DOCX, XLSX, and PDF. The role differs by file type:

• DOCX / XLSX — Ollama is the primary (and only) translator; it handles all text directly.
• PDF — Ollama works alongside the selected primary engine (Google, DeepL, etc.). Because translating Chinese to English typically expands text by 2–3×, some blocks would overflow their original bounding boxes. Ollama receives both the source text and the physical character budget of each box, translating only the layout-constrained blocks while the primary engine handles the rest.

	HY-MT 1.5 1.8B · Tencent	Qwen3.5 4B · Alibaba
Size	~1.1 GB	~2.4 GB
Languages	33 major languages	Broad coverage
Speed	Faster (smaller model)	Slower
PDF routing	All blocks	Layout-constrained blocks only
DOCX / XLSX	✓	✓

HY-MT is a purpose-built translation model. For PDF it translates every block directly; for DOCX/XLSX it translates all text as the primary engine.

Qwen is a general-purpose LLM. For PDF, it first classifies each block to decide which need layout-constrained translation and which can go to the primary engine - giving smarter results on complex layouts. For DOCX/XLSX it also acts as the primary translator.

Ollama is installed automatically on first use. Models are downloaded on first translation and stored in %USERPROFILE%\.ollama\models\ (Windows), outside the app folder.

Project Structure

Click to expand

src/
  Origin/
  Output/
  verbilo/
    launch.py
    cli.py
    main.py         - `translate_file()` core API
    gui/
      app.py        - CustomTkinter GUI
      config.py
      helpers.py
      theme.py
      icons.py
    converters/
      docx_converter.py
      xlsx_converter.py
      pdf_converter.py
    translators/
      azure.py
      baidu.py
      base.py
      cache.py
      deepl.py
      factory.py
      google.py
      http_session.py
      lang_detect.py
      local.py
      usage.py
    assets/
      __init__.py
    utils/
      io.py
pyproject.toml
requirements.txt
README.md

Nuitka build (Windows)

Prerequisites:

• A Python virtual environment (recommended) activated.
• nuitka installed in the virtualenv (pip install nuitka).

Build the GUI executable:

# From the repository root, with your virtualenv active
.venv\Scripts\python.exe scripts\build_nuitka.py --entry gui --output dist/nuitka

Notes:

• For a final GUI build without a console window, pass the flag --windows-console-mode=disable to the underlying Nuitka command (the helper script already exposes this behavior when appropriate).
• If build fails and you try with changes, clean the Nuitka cache at %LOCALAPPDATA%\Nuitka\Nuitka\

Run the built GUI directly by double-clicking the verbilo.exe in Explorer to launch without the console.

Troubleshooting:

• You will need the language model used by fasttext detector, run download_models.py to download models/lid.176.bin. For Local use, you will also need the OPUS-MT model, each language source+target is a diferent model.
• If paths or behavior differ, confirm you executed the commands from the repository root and that your virtualenv has nuitka installed.

Requirements & Notes

• Python: 3.12+
• Install (has all): pip install -r requirements.txt
• GUI extras: pip install customtkinter pytablericons Pillow
• Detection engines:
  • Lingua: high accuracy for short strings (heavier).
  • FastText: very fast, good balance.

Notes:

• Scanned (image-only) PDFs are detected and skipped - they will be logged rather than producing broken output.
• When a specific source language is set, local detection prevents unnecessary API translation calls.
• Verbilo batches segments to reduce API usage and avoid rate limits.

Contributing

Contributions are what makes open source great!

• Found a bug? Open an issue with steps to reproduce and a sample file if possible
• Want to add features? Fork, create a feature branch, and open a PR referencing the issue
• PR checklist:
  • Keep changes focused and minimal
  • Follow existing code style
• Development tips:
  • Run unit tests locally before
  • Any change needs to be documented, even if small

Acknowledgments

• Tabler Icons / pytablericons for GUI icons.
• PyMuPDF for in-place PDF text editing.
• Lingua, FastText for language detection options.
• Everyone who files issues and contributes patches.

License

This project is released under the GNU Affero General Public License v3 (AGPL-3.0-or-later) — see the LICENSE file for details.