Multi-LLM Translation Assistant

An automated Python translation assistant that monitors for jobs, processes documents (.docx, .pptx, .xlsx), and uses multiple LLMs (GPT, Claude, Gemini) for high-quality, comparable translations and critiques.

---

Overview

This tool is designed to automate the "first pass" of a translation workflow. It solves the tedious problem of manually preparing documents, sending them to various services, and collating the results. It runs as a headless background service that can watch for new jobs in a CSV file or new files in a "hot folder," process them automatically, and regenerate fully-formatted documents with the translated text.

It is controlled by a powerful, interactive web interface (UI) that allows for real-time configuration, job monitoring, and side-by-side comparison of translation results.

Key Features

• Interactive Web UI: A Streamlit dashboard for reviewing translations, viewing logs, and configuring the application on the fly.
• Live Configuration Reload: Change settings like the operation mode or primary model in the UI, and the background service will reload the new configuration without restarting.
• Automated Job Monitoring: A headless service watches a CSV file for new job tickets or a local "hot folder" for new file drops.
• Multi-LLM Engine: Utilizes GPT, Claude, and Gemini to perform translations, allowing for robust quality comparison.
• Complex Document Support: Extracts text from and regenerates .docx, .pptx, and .xlsx files, preserving basic structure.
• Advanced Workflows:
  • Parallel Mode: Get translations from all LLMs simultaneously.
  • Critique Mode: One LLM translates, and the others provide constructive feedback and a refined version.
• Professional Tooling:
  • Glossary Support: Enforces consistent terminology via a glossary.json file.
  • Colored Logging: Clean, color-coded console output and a detailed app.log file for easy debugging.

Integration with GengoWatcher

This assistant is the perfect companion to the GengoWatcher-Public application. While GengoWatcher-Public finds new translation jobs, this assistant automatically processes them. By pointing this assistant to the CSV file generated by GengoWatcher, you create a fully automated pipeline: from job discovery to final, multi-model translation.

How It Works

The application is now split into two main components:

1. The Headless Service (run_service.py): This is the core engine. It runs continuously in the background and contains the two worker threads that monitor for new jobs.
2. The User Interface (run_ui.py): This is a separate Streamlit application that acts as the control panel and viewer. It communicates with the service via signal files in the monitor/ directory.

Getting Started

Prerequisites

• Python 3.9+
• Linux-Specific Dependency: The pyperclip library requires a command-line copy/paste tool to function. Please install one for your distribution:
  • Arch Linux: sudo pacman -S xclip
  • Debian/Ubuntu: sudo apt install xclip
  • Fedora: sudo dnf install xclip

Installation

1. Clone the repository:

   git clone https://github.com/tdawe1/multi-llm-translator.git
   cd multi-llm-translator

2. Set up a Python virtual environment:

   python -m venv .venv
   source .venv/bin/activate

3. Install the required dependencies:

   pip install -r requirements.txt

4. Configure your API keys:

   • Create your environment file from the example:

     cp .env.example .env

   • Edit the .env file and add your secret API keys.

Usage

The application requires two separate terminals to run for interactive use.

Step 1: Run the Service (Terminal 1)

This script runs the background workers that monitor for and process jobs.

python run_service.py

Step 2: Run the UI (Terminal 2)

This command launches the Streamlit web interface, which will open in your browser.

streamlit run run_ui.py

Running as a systemd Service (Recommended for Production)

To run the application reliably in the background and have it start automatically on boot, setting it up as a systemd user service is the recommended method.

1. Create the Service File: Create a new file at ~/.config/systemd/user/translator.service and paste the following content into it.

Important: You must replace /home/multi-llm-translator with the absolute path to your project directory.

[Unit]
Description=Multi-LLM Translation Assistant Service
After=network.target

[Service]
# Replace with the absolute path to your project's root directory
WorkingDirectory=/home/multi-llm-translator

# Replace with the absolute path to the python executable in your .venv
ExecStart=/home/multi-llm-translator/.venv/bin/python /home/multi-llm-translator/run_service.py

Restart=on-failure
RestartSec=5s

[Install]
WantedBy=default.target

2. Manage the Service: After creating the file, reload the systemd daemon:

systemctl --user daemon-reload

You can now manage the service with the following commands:

• Start: systemctl --user start translator.service
• Check Status: systemctl --user status translator.service
• Stop: systemctl --user stop translator.service
• View Logs: journalctl --user -u translator.service -f
• Enable on Boot: systemctl --user enable translator.service

Configuration

Configuration can be managed in two ways:

1. Using the .env File (Initial Setup)

All startup settings are controlled from your .env file.

Setting	Options	Description
OPERATION_MODE	SIMPLE, PARALLEL, CRITIQUE	Defines the translation workflow.
PRIMARY_MODEL	gpt, claude, gemini	The main model to use for SIMPLE and CRITIQUE modes.
DUMMY_MODE	True, False	If True, the app simulates API calls without using tokens for free testing.

2. Using the Web UI (Live Reload)

The UI sidebar allows you to change the OPERATION_MODE, PRIMARY_MODEL, and DUMMY_MODE at any time. When you click "Save and Reload Service," the UI updates the .env file and signals the background service to reload the new settings without a restart.

Future Work

• Advanced Document Regeneration: Add support for preserving more complex formatting (styles, tables, images).
• Robust Job Status Tracking: Implement a more robust system (e.g., SQLite database) for tracking job status.
• Text-based UI (TUI): Create a third entry point for a fully interactive terminal dashboard.

License

This project is licensed under the 0BSD License. See the LICENSE file for details.