Professional-quality English-to-Armenian literary translation powered by LLMs. This tool emulates the workflow of a top-tier human literary translator: it reads the entire book, deeply analyses style and content, builds a Translation Bible, translates chapter-by-chapter with full context, and iteratively refines each translation using an LLM-as-Judge quality loop.
Supports three backends:
- Google Gemini (cloud) — best quality with gemini-2.5-pro/flash
- OpenRouter (cloud) — access 200+ models including free ones like
qwen/qwen3.6-plus:free - Ollama (local/offline) — hybrid stack with translation-specialized + reasoning models
- Full-book analysis — builds a Translation Bible with character profiles, glossary, style analysis, themes, and motifs before translating a single word
- Context-aware translation — each chapter is translated with the Translation Bible, previous chapter summaries, and recently translated chapters injected as context
- RL-inspired quality loop — an independent LLM critic evaluates every chapter across 6 dimensions (semantic fidelity, fluency, style preservation, character voice, literary quality, cultural appropriateness) and triggers automatic revisions when scores fall below thresholds
- Resume support — interrupted translations can be resumed from the last completed chapter
- Multiple input formats — PDF, EPUB, and TXT
- Multiple output formats — Markdown and EPUB (via pandoc)
- Three LLM backends — Gemini (cloud), OpenRouter (cloud, free tier available), Ollama (local/offline)
- Heuristic quality pre-checks — zero-cost deterministic checks (script consistency, length ratio, paragraph preservation) catch catastrophic failures before spending LLM tokens
- Score-calibrated evaluation — strict scoring anchors prevent score inflation in the quality loop
- Armenian-specific grammar guidance — SOV structure, case system, em-dash dialogue, and other Eastern Armenian rules baked into prompts
- Cost estimation — shows estimated API cost before starting and asks for confirmation
- Side-by-side review — generates a review file with original and translated text for human review
# Clone the repository
git clone https://github.com/Edmon02/ArmenianLitTranslator.git
cd ArmenianLitTranslator
# Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate
# Install the package
pip install -e .
# Optional: install pandoc for EPUB output
# macOS:
brew install pandoc
# Ubuntu/Debian:
# sudo apt install pandoc- Go to Google AI Studio
- Create a new API key
- Copy the key
cp .env.example .env
# Edit .env and add your API key(s):
# GEMINI_API_KEY=your-gemini-api-key-here (for Gemini backend)
# OPENROUTER_API_KEY=your-openrouter-api-key (for OpenRouter backend)You only need keys for the backend(s) you plan to use. Ollama requires no API key.
armenian-lit-translator translate mybook.pdfarmenian-lit-translator translate mybook.epub \
--output-dir ./my-translation \
--model gemini-2.5-pro \
--max-iterations 3 \
--temperature 0.2armenian-lit-translator translate mybook.epub --resumearmenian-lit-translator setup-local \
--model translategemma:4b \
--reasoning-model qwen2.5:7b
armenian-lit-translator translate mybook.txt \
--backend ollama \
--local-model translategemma:4b \
--local-reasoning-model qwen2.5:7b# Free model (qwen3.6-plus) — $0 cost
armenian-lit-translator translate mybook.pdf --backend openrouter
# Specific model
armenian-lit-translator translate mybook.pdf \
--backend openrouter \
--openrouter-model qwen/qwen3.6-plus:freearmenian-lit-translator translate mybook.txt --yesarmenian-lit-translator --help
armenian-lit-translator translate --helpgemini-2.5-pro— best literary translation quality, 1M context windowgemini-2.5-flash— faster/cheaper, slightly lower quality
qwen/qwen3.6-plus:free— 1M context, 65K output tokens, $0 cost (free tier)
- Best quality on Mac:
gemma3:12b - Best hybrid stack:
translategemma:4b(translation) +qwen2.5:7b(analysis/evaluation) - Upgrade from 4B:
translategemma:12b
Using gemini-2.5-pro with default settings (avg 1.5 revision rounds/chapter):
| Phase | Est. Tokens | Est. Cost |
|---|---|---|
| Analysis | ~150,000 | $0.25 |
| Translation | ~900,000 | $3.50 |
| Quality Evaluation | ~300,000 | $1.20 |
| Total | ~1,350,000 | ~$5.00 |
Actual costs may vary +/- 50% depending on book complexity, chapter count, and how many revision rounds are triggered. A very complex literary work with many revision rounds could cost up to $10-15.
After translation, you'll find in the output directory:
| File | Description |
|---|---|
{title}_armenian.md |
Full Armenian translation in Markdown |
{title}_armenian.epub |
EPUB version (if pandoc is installed) |
translation_bible.json |
Machine-readable Translation Bible |
translation_bible.md |
Human-readable Translation Bible |
glossary.md |
English-Armenian glossary |
{title}_review.md |
Side-by-side review file |
chapters/chapter_NNN.md |
Individual translated chapters |
progress.json |
Resume checkpoint |
translation.log |
Detailed log |
Prompts live in src/armenian_lit_translator/prompts.py and src/armenian_lit_translator/prompts_local.py. You can modify:
translation_system_prompt()— the main translator persona and CoT instructionsevaluation_system_prompt()— the critic persona and scoring criteria- Local translation prompts — optimized for small Ollama models and TranslateGemma
- Few-shot examples — embedded in the cloud translation prompt
In .env or via CLI:
--max-iterations 5— more revision rounds (costs more tokens)- Edit
config.pyto changemin_overall_score(default 9.0) ormin_dimension_score(default 8.0) - Lower thresholds = fewer revisions = faster/cheaper but potentially lower quality
book_loader → book_analyzer → translation_engine ↔ quality_evaluator → output_assembler
↕
resume_manager
- book_loader — extracts text and splits into chapters (PDF/EPUB/TXT)
- book_analyzer — two-pass analysis producing a Translation Bible
- translation_engine — translates with context injection + refinement loop
- quality_evaluator — heuristic pre-checks + LLM critic with 6-dimension scoring
- output_assembler — Markdown + EPUB + review file generation
- gemini_client — Google Gemini API wrapper with retry logic and token tracking
- openrouter_client — OpenRouter API client (OpenAI-compatible, free tier support)
- local_client — Ollama backend with repetition detection and multi-tier JSON repair
- resume_manager — checkpoint/resume persistence
- Armenian quality depends on Gemini's Armenian capability — while Gemini handles Armenian well, it is stronger in English. The evaluation scores may not perfectly correlate with native speaker perception.
- Chapter detection is heuristic — works well for books with clear chapter headings. Poorly formatted PDFs or books without chapter markers fall back to fixed-size splitting.
- PDF quality varies — scanned PDFs or PDFs with complex layouts may not extract cleanly. Use EPUB or TXT when possible.
- No OCR — the tool does not perform OCR on scanned PDFs.
- Cost is estimated, not exact — pre-translation cost estimates are rough (+/- 50%).
MIT