{"id":35462541,"url":"https://github.com/hydropix/translatebookwithllm","last_synced_at":"2026-01-08T23:02:16.214Z","repository":{"id":294827512,"uuid":"988184458","full_name":"hydropix/TranslateBookWithLLM","owner":"hydropix","description":"A python script designed to translate large amounts of text with an LLM, Ollama, OpenAI, Gemini and OpenRouter API","archived":false,"fork":false,"pushed_at":"2025-12-29T23:03:43.000Z","size":2743,"stargazers_count":450,"open_issues_count":7,"forks_count":55,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-31T14:37:55.291Z","etag":null,"topics":["epub","gemini","gemini-api","llm","lmstudio","local-llm","localization-tool","ollama","openai-api","openrouter","srt-subtitles","translation","translation-tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hydropix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-22T07:16:43.000Z","updated_at":"2025-12-29T23:03:47.000Z","dependencies_parsed_at":"2025-05-22T09:03:34.476Z","dependency_job_id":"16e586a7-27d9-45a0-91ba-26ba5e4b512c","html_url":"https://github.com/hydropix/TranslateBookWithLLM","commit_stats":null,"previous_names":["hydropix/translatebookwithllm"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hydropix/TranslateBookWithLLM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydropix%2FTranslateBookWithLLM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydropix%2FTranslateBookWithLLM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydropix%2FTranslateBookWithLLM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydropix%2FTranslateBookWithLLM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hydropix","download_url":"https://codeload.github.com/hydropix/TranslateBookWithLLM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydropix%2FTranslateBookWithLLM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28250247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-08T02:00:06.591Z","response_time":241,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["epub","gemini","gemini-api","llm","lmstudio","local-llm","localization-tool","ollama","openai-api","openrouter","srt-subtitles","translation","translation-tool"],"created_at":"2026-01-03T09:00:36.257Z","updated_at":"2026-01-08T23:02:16.207Z","avatar_url":"https://github.com/hydropix.png","language":"Python","funding_links":[],"categories":["The latest additions 🎉"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/hydropix/TranslateBookWithLLM/blob/main/src/web/static/TBL-Logo.png?raw=true\" alt=\"TBL Logo\"\u003e\n\u003c/p\u003e\n\n# TranslateBook with LLM (TBL)\n\nTranslate books, subtitles, and documents using AI - locally or in the cloud.\n\n**Formats:** EPUB, SRT, TXT | **Providers:** Ollama (local), OpenRouter, OpenAI, Gemini\n\n\u003e 📊 **[Translation Quality Benchmarks](https://github.com/hydropix/TranslateBookWithLLM/wiki)** — Find the best model for your target language.\n\n---\n\n## Quick Start\n\n**Prerequisites:** [Python 3.8+](https://www.python.org/downloads/), [Ollama](https://ollama.com/), [Git](https://git-scm.com/)\n\n```bash\ngit clone https://github.com/hydropix/TranslateBookWithLLM.git\ncd TranslateBookWithLLM\nollama pull qwen3:14b    # Download a model\n\n# Windows\nstart.bat\n\n# Mac/Linux\nchmod +x start.sh \u0026\u0026 ./start.sh\n```\n\nThe web interface opens at **http://localhost:5000**\n\n---\n\n## Choosing a Model\n\n| VRAM | Model | Best For |\n|------|-------|----------|\n| 8 GB | `gemma3:12b` | Spanish, Portuguese, European |\n| 24 GB | `mistral-small:24b` | French |\n| 24 GB | `gemma3:27b` | Japanese, Korean, Arabic, most languages |\n| 24 GB | `qwen3:30b-instruct` | Chinese (Simplified/Traditional) |\n\n\u003e 📊 **[Full benchmarks](https://github.com/hydropix/TranslateBookWithLLM/wiki)** — 11 models × 19 languages with accuracy, fluency \u0026 style scores.\n\n---\n\n## LLM Providers\n\n| Provider | Type | Setup |\n|----------|------|-------|\n| **Ollama** | Local | [ollama.com](https://ollama.com/) |\n| **OpenAI-Compatible** | Local | llama.cpp, LM Studio, vLLM, LocalAI... |\n| **OpenRouter** | Cloud (200+ models) | [openrouter.ai/keys](https://openrouter.ai/keys) |\n| **OpenAI** | Cloud | [platform.openai.com](https://platform.openai.com/api-keys) |\n| **Gemini** | Cloud | [Google AI Studio](https://makersuite.google.com/app/apikey) |\n\n\u003e **OpenAI-Compatible servers:** Use `--provider openai` with your server's endpoint (e.g., llama.cpp: `http://localhost:8080/v1/chat/completions`, LM Studio: `http://localhost:1234/v1/chat/completions`)\n\nSee [docs/PROVIDERS.md](docs/PROVIDERS.md) for detailed setup instructions.\n\n---\n\n## EPUB Translation Modes\n\n| Mode | Use When |\n|------|----------|\n| **Standard** (default) | Large model (\u003e12B), formatting is important |\n| **Fast Mode** (`--fast-mode`) | Small model (≤12B), reader compatibility issues, simpler is better |\n\nFast Mode strips HTML and outputs EPUB 2.0 for maximum compatibility. See [docs/FAST_MODE.md](docs/FAST_MODE.md) for details.\n\n---\n\n## Command Line\n\n```bash\n# Basic\npython translate.py -i book.epub -o book_zh.epub -sl English -tl Chinese\n\n# With Fast Mode\npython translate.py -i book.epub -o book_zh.epub --fast-mode\n\n# With OpenRouter\npython translate.py -i book.txt -o book_fr.txt --provider openrouter \\\n    --openrouter_api_key YOUR_KEY -m anthropic/claude-sonnet-4\n\n# With OpenAI\npython translate.py -i book.txt -o book_fr.txt --provider openai \\\n    --openai_api_key YOUR_KEY -m gpt-4o\n\n# With Gemini\npython translate.py -i book.txt -o book_fr.txt --provider gemini \\\n    --gemini_api_key YOUR_KEY -m gemini-2.0-flash\n\n# With local OpenAI-compatible server (llama.cpp, LM Studio, vLLM, etc.)\npython translate.py -i book.txt -o book_fr.txt --provider openai \\\n    --api_endpoint http://localhost:8080/v1/chat/completions -m your-model\n```\n\n### Main Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-i, --input` | Input file | Required |\n| `-o, --output` | Output file | Auto |\n| `-sl, --source_lang` | Source language | English |\n| `-tl, --target_lang` | Target language | Chinese |\n| `-m, --model` | Model name | mistral-small:24b |\n| `--provider` | ollama/openrouter/openai/gemini | ollama |\n| `--fast-mode` | Fast Mode for EPUB | Off |\n\nSee [docs/CLI.md](docs/CLI.md) for all options and examples.\n\n---\n\n## Configuration (.env)\n\nCopy `.env.example` to `.env` and edit:\n\n```bash\n# Provider\nLLM_PROVIDER=ollama\n\n# Ollama\nAPI_ENDPOINT=http://localhost:11434/api/generate\nDEFAULT_MODEL=mistral-small:24b\n\n# API Keys (if using cloud providers)\nOPENROUTER_API_KEY=sk-or-v1-...\nOPENAI_API_KEY=sk-...\nGEMINI_API_KEY=...\n\n# Performance\nMAIN_LINES_PER_CHUNK=25\nREQUEST_TIMEOUT=900\n```\n\n---\n\n## Docker\n\n```bash\ndocker build -t translatebook .\ndocker run -p 5000:5000 -v $(pwd)/translated_files:/app/translated_files translatebook\n```\n\nSee [DOCKER.md](DOCKER.md) for more options.\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Ollama won't connect | Check Ollama is running, test `curl http://localhost:11434/api/tags` |\n| Model not found | Run `ollama list`, then `ollama pull model-name` |\n| Timeouts | Increase `REQUEST_TIMEOUT` or reduce `MAIN_LINES_PER_CHUNK` |\n| EPUB won't open | Try `--fast-mode` |\n| Placeholders in output (⟦TAG0⟧) | Use `--fast-mode` |\n\nSee [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more solutions.\n\n---\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [docs/PROVIDERS.md](docs/PROVIDERS.md) | Detailed provider setup (Ollama, LM Studio, OpenRouter, OpenAI, Gemini) |\n| [docs/FAST_MODE.md](docs/FAST_MODE.md) | EPUB Fast Mode explained |\n| [docs/CLI.md](docs/CLI.md) | Complete CLI reference |\n| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Problem solutions |\n| [DOCKER.md](DOCKER.md) | Docker deployment guide |\n\n---\n\n## Links\n\n- [Report Issues](https://github.com/hydropix/TranslateBookWithLLM/issues)\n- [OpenRouter Models](https://openrouter.ai/models)\n\n---\n\n**License:** AGPL-3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydropix%2Ftranslatebookwithllm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhydropix%2Ftranslatebookwithllm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydropix%2Ftranslatebookwithllm/lists"}