DocuLingo

A command-line tool to translate large documents using language models. It preserves the file formatting and simplifies migrating documentation to other languages.

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• CLI Reference
• Configuration
• Limitations
• Development
• License

Overview

doculingo helps you translate documents while preserving their formatting. It currently works with Word files and aims to support additional formats in the future, making it ideal for projects that require multiple language versions without losing the original layout.

Key Features

• ✨ Automatic Translation — uses OpenAI to safely translate paragraphs.
• 📝 Preserves Styles — copies fonts, colors, and alignment to the translated version.
• 📄 Document Support — currently handles large .docx files with more formats planned.
• 🔁 Automatic Retries — retries with exponential backoff when the API fails and exits with a clear error if all retries fail.
• ⚙️ Simple CLI — clear commands with built-in help.

Installation

Run instantly with uv without installing:

uvx doculingo --help

Or install from PyPI:

pip install doculingo

Quick Start

Translate a Word document from Spanish to English:

doculingo word \
  --input file.docx \
  --output translated.docx \
  --language-source spanish \
  --language-target english

CLI Reference

Get the full list of options with:

doculingo --help

The main subcommand is word, designed for .docx files:

Example using a different model and fewer retries:

doculingo word \
  --input file.docx \
  --output translated.docx \
  --language-source spanish \
  --language-target english \
  --model gpt-4o-mini \
  --retries 3

Configuration

doculingo reads configuration from environment variables (a local .env file is also supported). Copy .env.example to .env and fill in your values:

The model can be selected per run with --model; it defaults to gpt-4o.

Limitations

• Only top-level document paragraphs are translated. Content inside tables, headers and footers, and paragraphs inside shapes (text boxes, SmartArt) is not translated.
• Paragraphs made of multiple runs (mixed formatting within a paragraph) are translated as a whole, so their internal formatting is collapsed into a single run in the output document.
• The output document is rebuilt from paragraphs only, so other document parts such as images and tables are not carried over.

Development

Install the dependencies and run the tool locally:

uv lock
uv sync --all-groups --all-extras
uv run doculingo --help

Common tasks are available through the makefile:

make install     # uv sync --all-groups --all-extras
make format      # ruff format
make lint        # ruff check
make type-check  # mypy doculingo
make test        # pytest

License

Distributed under the MIT license. See the license file.