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:

Option	Required	Default	Description
--input, -i	Yes	—	Input .docx file path.
--output, -o	Yes	—	Output file path. The .docx suffix is appended if missing.
--language-source, -s	Yes	—	Source language. For example: spanish.
--language-target, -t	Yes	—	Target language. For example: english.
--translator	No	openai	Translator implementation. Only openai is available for now.
--model	No	gpt-4o	Model used by the translator.
--retries	No	5	Number of retries after the first failed translation attempt, with exponential backoff.

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:

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key used by the OpenAI translator. Get one at platform.openai.com/api-keys.

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.