Translate PDF, Word, Excel, and PowerPoint files while preserving the original format and style — powered by Ollama, MLX, or LMStudio, with automatic source-language detection.
What is XteVision TransDocs and who is it for?
XteVision TransDocs is a Python script and web GUI for translating Microsoft Office files and PDFs while keeping the original format and style. It uses the Ollama, MLX, or LMStudio API and can automatically detect the source language from a minimum of 50 words, or accept a manually specified source language.
This tool is built for production-scale workloads as well as personal translation tasks. It supports multiple UI languages (EN, CN, DE) and three interchangeable AI backends, so it fits both single-user and enterprise deployments.
What TransDocs can do
Detects the source language by analyzing at least 50 words from the document.
Override detection with the -s / --src_lang argument for OCR-friendly output.
Translates paragraphs, tables, headers, and footers while preserving layout.
Uses embedded text when available; scanned pages fall back to Poppler + Tesseract OCR.
Run against Ollama, MLX, or LMStudio — whichever fits your infrastructure.
For important PDFs, verify each page with the vision model before translating.
Software and system packages you need
python-docx, python-pptx, openpyxl, Pillow, pytesseract, python-dotenv, requests, langdetect, flask, werkzeugpoppler-utils (pdftoppm or pdftocairo in PATH) and tesseract-ocr with the language packs your documents needTRANSDOC_API_TOKEN if your backend requires authenticationSet up the environment and install dependencies
cd TransDocs
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -r requirements.txtsudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-engAdd more Tesseract language packs as needed for your source documents.
Adjust the settings in .env as needed. See the Configuration section for the full list of supported keys.
Runtime settings in the .env file
Settings can be managed through .env, similar to the invoicer setup. Supported keys include:
| Key | Purpose |
|---|---|
| TRANSDOC_PROVIDER | Selected backend provider |
| TRANSDOC_OLLAMA_URL | Ollama base URL |
| TRANSDOC_MLX_URL | MLX backend URL |
| TRANSDOC_LM_STUDIO_URL | LMStudio backend URL |
| TRANSDOC_DEFAULT_MODEL | Model used when none is specified |
| TRANSDOC_API_TOKEN | Authentication token for the backend |
| TRANSDOC_UPLOAD_DIR | Directory for uploaded files |
| TRANSDOC_OUTPUT_DIR | Directory for translated output |
| TRANSDOC_SECRET_KEY | Flask session secret key |
| TRANSDOC_HOST | Host the web app binds to |
| TRANSDOC_PORT | Port the web app binds to |
| TRANSDOC_DEBUG | Enable Flask debug mode |
| TRANSDOC_LOG_FILE | Path to the log file |
| TRANSDOC_TESSERACT_LANGS | Explicit OCR languages (e.g. eng+deu) |
Translate documents from the terminal
The transdoc.py script can be run from the command line. For PDF input, the workflow is hybrid: text PDFs are extracted directly, while scanned or image-only pages fall back to OCR. If you already know the source language, passing -s improves OCR language selection. Both the CLI and Flask app load .env automatically, and the CLI supports backend selection with -p/--provider and -b/--base_url.
| Flag | Name | Description |
|---|---|---|
| -i | input_file | Path to the input document (required) |
| -o | output_file | Path to save the translated document (required) |
| -t | target_lang | Target language code (e.g. en, de, fr) (required) |
| -k | api_token | API token for authentication (required) |
| -m | model | Model name to use (e.g. llama3.2) |
| -s | src_lang | Source language code (detected automatically if omitted) |
Translate with automatic source-language detection:
python transdoc.py -i input.docx -o output.docx -t en -k your_api_tokenTranslate from a specified source language:
python transdoc.py -i input.docx -o output.docx -t en -k your_api_token -s frTranslate using a specific model:
python transdoc.py -i input.docx -o output.docx -t en -k your_api_token -m custom_modelOptional Flask-based interface
A web-based interface enhances usability by letting users upload documents and receive translations without the command line. This is a suggested implementation using Flask and is currently untested.
pip install flask werkzeugpython app.pyOpen a browser at http://localhost:5000, then:
.docx file to translateMonitoring and debugging output
The script logs detailed information to both the console and a file named translation_debug.log. Logging defaults to the DEBUG level, capturing all message levels.
To reduce console verbosity, change the logging level in the script:
console_handler.setLevel(logging.INFO) # Change DEBUG to INFOCommon issues and solutions
DEBUG.-s to specify the source language.TRANSDOC_TESSERACT_LANGS, e.g. export TRANSDOC_TESSERACT_LANGS=eng+deu.pdftoppm or pdftocairo is in PATH.translation_debug.log.app.run(debug=True, port=5001).