Translate PDF and Office documents through a reviewable, format-aware workflow.

中文完整指南

---

What it does

Local Translation Agent is a self-hosted document translation workbench for PDF, Excel, Word, PowerPoint, text, subtitles, JSON, EPUB, and HTML. It combines a FastAPI service, a React interface, a job queue, short-lived file storage, and format-specific validation.

The project can use a local Ollama-compatible model or connect to compatible HTTP translation services. "Local-first" describes the supported deployment path, not a guarantee: files may leave the device when a remote engine is configured.

Capability map

Document	Processing path	Preservation and validation
PDF	BabelDOC, PDFMathTranslate, or DocuTranslate	layout translation, residual-text inspection, overlap and clipping checks
PowerPoint	dedicated OOXML translation agent	text boxes, tables, notes, theme/media preservation, optional LibreOffice rendering
Excel	DocuTranslate workflow	workbook output validation and bilingual cell layout support
Word / EPUB	DocuTranslate workflow	package validation after translation
TXT / Markdown / subtitles / JSON / HTML	DocuTranslate workflow	format-specific routing and downloadable result

Processing flow

Browser upload
      |
      v
FastAPI + identity / CSRF checks
      |
      +----> SQLite job metadata
      |
      v
Inline or Redis-backed queue
      |
      v
Format router
  |        |          |
 PDF     PPTX      Office / text
  |        |          |
  v        v          v
Engine -> validation -> result with expiry

Source and intermediate files are cleaned after completion or failure. Results default to a 24-hour retention window controlled by RESULT_TTL_HOURS.

Quick start

Requirements: Python 3.12, uv, Node.js, and npm.

cp .env.example .env
uv sync --extra dev --python 3.12
npm --prefix frontend install
npm --prefix frontend run build
uv run uvicorn app.main:app --host 127.0.0.1 --port 8080

Open http://127.0.0.1:8080. The default development configuration uses the safe workflow fixture:

AUTH_MODE=development
TRANSLATION_MODE=demo

demo verifies upload, queue, status, validation, and download behavior by returning a copy. It does not perform a real translation.

Real translation

For a local Ollama and BabelDOC setup:

TRANSLATION_MODE=remote
PDF_ENGINE=babeldoc
BABELDOC_EXECUTABLE=/path/to/babeldoc/python
BABELDOC_RUNNER=./scripts/run_babeldoc.py
BABELDOC_OLLAMA_HOST=http://127.0.0.1:11434
MODEL_BASE_URL=http://127.0.0.1:11434/v1
MODEL_API_KEY=ollama
MODEL_ID=qwen3:4b-q4_K_M

Other supported adapters include PDFMathTranslate and DocuTranslate. PowerPoint render validation benefits from LibreOffice. Scanned-PDF parsing can be delegated to a configured MinerU or Docling path.

Authentication and deployment

• development: local development identity.
• personal: standalone username and password-hash mode.
• wecom: optional Enterprise WeChat OAuth integration for organization identity.
• QUEUE_BACKEND=inline: simplest single-process development mode.
• Redis queue: separates the API and translation worker for longer-running jobs.

Start from .env.example; keep real secrets in the untracked .env file.

Privacy boundary

• Local Ollama and local document engines can keep processing on infrastructure you control.
• Remote model or translation endpoints receive the data required by their adapter. Review the provider's retention and training policy before use.
• Uploaded files are temporary, but operators remain responsible for storage permissions, backups, logs, and configured retention.
• The repository does not include a hosted service or promise compliance for a particular jurisdiction.

Development checks

uv run ruff check .
uv run pytest
npm --prefix frontend run build

Repository map

app/                  FastAPI API, workers, engines, validation, storage
frontend/             React upload and task workbench
scripts/              BabelDOC, DocuTranslate, and PDFMath runners
deploy/               reverse-proxy configuration
tests/                API, lifecycle, engine, PDF, PPTX, and auth tests
.env.example          documented runtime configuration

Limitations

• Translation quality depends on the selected model, engine, language pair, and source-document structure.
• Format preservation is validated but cannot guarantee pixel-identical output for every document.
• Scanned documents require OCR or a parsing service and may need manual review.
• Enterprise deployment still requires operator-owned identity, network, malware scanning, backup, and observability controls.

License

Released under the MIT License. Review THIRD_PARTY_NOTICES.md and the licenses and service terms of every engine, model, and font you configure.