Skip to content
Back to search

book-translate-lite

MarketplaceWorks with Claude CodeGitHub

Translate whole books with AI agents, end to end, at low token cost.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nt0wers84--book-translate-lite/badge.svg)](/listings/nt0wers84--book-translate-lite)

HTML

<a href="/listings/nt0wers84--book-translate-lite"><img src="/api/listings/nt0wers84--book-translate-lite/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Claude Code:**

/plugin marketplace add NT0wers84/book-translate-lite
/plugin install book-translate-lite@book-translate-lite

**Codex:**

codex plugin marketplace add NT0wers84/book-translate-lite
codex plugin add book-translate-lite@book-translate-lite

**Manual install** (both apps, plus a `btl` command in your terminal):

git clone https://github.com/NT0wers84/book-translate-lite.git
cd book-translate-lite && ./install.sh

Requirements:

- Python 3.9+, [pandoc](https://pandoc.org/installing.html) and [Calibre](https://calibre-ebook.com). - For the hands-off background mode, also the [Codex CLI](https://github.com/openai/codex) or the [Claude Code CLI](https://docs.anthropic.com/claude-code). - Without a CLI, the agent translates inside the chat instead.

To see what is missing, ask the agent *"check the book translator setup"* or run `btl doctor`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "book-translate-lite",
  4. "description": "Translate whole books with AI agents, end to end, at low token cost.",
  5. "owner": {"name": "NT0wers84"},
  6. "plugins": [
  7. {
  8. "name": "book-translate-lite",
  9. "description": "Translate a whole book (EPUB/PDF/DOCX) into any language, end to end, with a final review and EPUB/DOCX/PDF output, using very few tokens.",
  10. "version": "2.3.0",
  11. "source": "./",
  12. "skills": ["./skills/book-translate-lite"],
  13. "author": {"name": "NT0wers84"},
  14. "homepage": "https://github.com/NT0wers84/book-translate-lite",
  15. "repository": "https://github.com/NT0wers84/book-translate-lite",
  16. "license": "MIT",
  17. "keywords": ["translation", "books", "epub", "pdf", "docx", "ebook"]
  18. }
  19. ]
  20. }
README.md · README · 200 lines
  1. # book-translate-lite
  2. **Translate a whole book into any language by asking your AI agent.** It runs to the end on its own and gives you the finished EPUB, DOCX and PDF plus a review report. It uses very few tokens.
  3. Works with **Claude Code** and **Codex** (app or CLI). Input formats: EPUB, PDF, DOCX and Markdown.
  4. ```
  5. You: Translate ~/Books/The Clockwork Lighthouse.epub into Italian.
  6. Agent: Started: 41 parts, en → it. It will translate, review and build the book on its own.
  7. Ask me "how is it going?" whenever you like.
  8. …
  9. You: How is it going?
  10. Agent: Il Faro a Orologeria — translating 28/41 (68%), running.
  11. …
  12. Agent: Finished. book/Il Faro a Orologeria.epub (+ docx, pdf). The review applied 37 fixes;
  13. 2 parts are worth a quick look (see review/FINAL_REPORT.md).
  14. ```
  15. ## Install
  16. **Claude Code:**
  17. ```
  18. /plugin marketplace add NT0wers84/book-translate-lite
  19. /plugin install book-translate-lite@book-translate-lite
  20. ```
  21. **Codex:**
  22. ```bash
  23. codex plugin marketplace add NT0wers84/book-translate-lite
  24. codex plugin add book-translate-lite@book-translate-lite
  25. ```
  26. **Manual install** (both apps, plus a `btl` command in your terminal):
  27. ```bash
  28. git clone https://github.com/NT0wers84/book-translate-lite.git
  29. cd book-translate-lite && ./install.sh
  30. ```
  31. Requirements:
  32. - Python 3.9+, [pandoc](https://pandoc.org/installing.html) and [Calibre](https://calibre-ebook.com).
  33. - For the hands-off background mode, also the [Codex CLI](https://github.com/openai/codex) or the [Claude Code CLI](https://docs.anthropic.com/claude-code).
  34. - Without a CLI, the agent translates inside the chat instead.
  35. To see what is missing, ask the agent *"check the book translator setup"* or run `btl doctor`.
  36. ## Use it
  37. Just talk to the agent. In Claude Code you can also type `/book-translate-lite …`.
  38. | you say | what happens |
  39. |---|---|
  40. | *Translate `book.epub` into French* | sets up the job and starts translating in the background |
  41. | *Translate it into German, title "Der Leuchtturm"* | the same, with the translated title |
  42. | *How is it going?* | progress, phase, where the book and the report are |
  43. | *Stop* / *Continue* | stops it, and later resumes it where it was |
  44. | *Translate this essay into Spanish* / *it's a programming manual* | picks the matching genre rules (`nonfiction`, `technical`, …) |
  45. | *Translate volume 2, it's the same series as the first one* | starts with the first volume's glossary, rules and style |
  46. | *Always translate "Brass Warden" as "Custode d’Ottone"* | adds a fixed glossary term |
  47. | *"Brass Warden" was wrong: fix it in the parts already done* | changes the term and rewrites it where it was already translated |
  48. | *Show the glossary* | lists the terms (fixed or proposed) |
  49. | *Use Claude for the review* / *Review it again* | reruns the final review, then rebuilds the book |
  50. | *Make a PDF* / *Rebuild the book* | builds the formats again |
  51. | *Check the setup* | lists what is installed and what is missing |
  52. The agent always asks for the target language if you did not give it.
  53. ## The `btl` command
  54. The agent uses one command, `btl`, and you can use it too:
  55. ```
  56. btl start BOOK --to LANG [--from LANG] [--title "…"] [--engine codex|claude] [--review-engine claude]
  57. [--genre GENRE] [--series PREV_JOB] [--workdir DIR]
  58. btl genre [JOB] [GENRE] btl series [JOB] --from PREV_JOB [--retro]
  59. btl status [JOB] btl stop [JOB] btl resume [JOB]
  60. btl review [JOB] [--again] [--flagged] [--engine claude]
  61. btl build [JOB] [--formats epub,docx,pdf]
  62. btl terms list [TEXT] | add SOURCE TARGET [--proposed] [--retro] | remove SOURCE
  63. btl config [JOB] [KEY=VALUE …] btl log [JOB] btl jobs btl doctor
  64. btl next [JOB] (in-chat mode: tells the agent which sub-agents to launch)
  65. btl import FOLDER (projects started with translate-book or v1)
  66. ```
  67. `JOB` can be the book file, its `<book>_temp` folder, or part of the title. Without it, `btl` uses the current folder's job or the most recent one.
  68. ## Series
  69. Volumes of the same series must share names and style. Start every later volume with `--series`:
  70. ```
  71. btl start "Volume 3.epub" --to it --series "Volume 2"
  72. ```
  73. The new job gets the previous volume's glossary (fixed and proposed terms), `rules.md` and house-style settings (genre, quotes, replacements, forbidden forms, all-caps names, table-of-contents title, rights line, engines and review settings), and its folder is created next to the previous job. If you forget `--series` and another job by the same author exists, `btl start` says so and waits before starting.
  74. For a job that is already under way, `btl series JOB --from PREV --retro` merges the glossary and rewrites, in the parts already translated, every term that had been rendered differently. A term changed later can be rewritten the same way with `btl terms add "X" "Y" --retro`. The rewrite works paragraph by paragraph, only where the source paragraph contains the term; run `btl review --again` afterwards to fix gender and number agreement.
  75. ## What it does
  76. ```
  77. book.epub ─▶ parts ─▶ translation in groups ─▶ checks ─▶ review ─▶ EPUB · DOCX · PDF
  78. (engine, in parallel) (scripts) (engine) + FINAL_REPORT.md
  79. ```
  80. 1. **Setup.** Calibre converts the book to Markdown, split into parts of about 6,000 characters, and recurring names are collected as glossary candidates.
  81. 2. **Translation.** Groups of 3 parts are translated in parallel. Every answer is checked: paragraphs, bold and italics, images, headings, glossary terms, forbidden forms. Rejected parts are retranslated with the list of errors. New names proposed by the model go into the glossary.
  82. 3. **Review.** The whole book is scanned:
  83. - terms rendered differently in different parts;
  84. - sentences left in the source language;
  85. - quote and punctuation problems.
  86. Then the review engine (which can be a different one, for example Claude) re-reads source and translation and makes targeted fixes. Fixes that would break the structure are rejected, and the originals are kept.
  87. 4. **Book.** pandoc builds the EPUB and DOCX and Calibre the PDF, with the correct language tag, a full table of contents and styled system messages. The cover comes from the original EPUB (or `images/cover.*`); scene breaks are never doubled. Optional title-page lines: `btl config subtitle="Series, volume 6" rights="Personal use only"`.
  88. 5. **Report.** `review/FINAL_REPORT.md` lists what is still worth a look.
  89. Everything stays in a `<book>_temp/` folder next to the book. You can stop and resume at any time.
  90. ### Why it uses few tokens
  91. With typical setups, most of the cost is the **orchestrating conversation**, which grows with every step. Here:
  92. - The orchestrator is a **script**. Each group of parts is a single model call with a self-contained task, so no model spends tokens coordinating.
  93. - Each task holds only what that group needs: the rules, the glossary terms that occur in those parts, and a short continuity excerpt.
  94. - Checks and typography fixes are done by scripts, not by the model.
  95. Details are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  96. ## Languages
  97. Any target language works. Some have a **profile** with typography and publishing conventions:
  98. | profile | quotes | notes |
  99. |---|---|---|
  100. | Italian `it` | «» | punctuation outside quotes, *passato remoto*, `Okay`→`Ok` |
  101. | French `fr` | « » | non-breaking spaces, *passé simple* |
  102. | Spanish `es` | «» | dialogue with raya, ¿ ¡ |
  103. | German `de` | „“ | Präteritum, consistent du/Sie |
  104. | English `en` | “” | |
  105. | `pt` `nl` `pl` `ja` `zh` `ko` | profile typography | generic rules |
  106. Adding a language takes a few lines: see [docs/LANGUAGES.md](docs/LANGUAGES.md). Pull requests are welcome.
  107. ## Genres
  108. `rules.md` = the language rules (above) + a **genre section** that fits the kind of book. Pick it with `btl start … --genre GENRE` or change it later with `btl genre GENRE` (only the genre section is rewritten; your own notes stay).
  109. | genre | for | main rules |
  110. |---|---|---|
  111. | `fiction` (default) | novels, short stories | character voices, dialogue conventions, talking names, adapted wordplay |
  112. | `nonfiction` | essays, history, biography, popular science | precision, established terminology, published translations of quotations, references untouched |
  113. | `technical` | manuals, programming, textbooks | code/commands/paths never translated, official UI localisation, one term per concept |
  114. | `children` | picture books, children's and YA | age-appropriate language, read-aloud rhythm, rebuilt rhymes and funny names |
  115. | `poetry` | poetry, verse | line-for-line, meaning > rhythm > rhyme |
  116. | `gamelit` | LitRPG, GameLit, system/stat-based stories | fixed formulas for system messages, consistent skill/item names, stat formats, chat lines |
  117. | `general` | anything else | only the language rules and glossary consistency |
  118. The genres live in `templates/genres/<genre>.md`; add one by dropping a file there. Anything specific to one book or series (house terms, names, forbidden forms) goes in that job's `rules.md`, `terms.json` and `project.json`, never in the skill.
  119. ## Settings
  120. Change settings by telling the agent, or with `btl config KEY=VALUE`. Everything is stored in the job's `project.json`.
  121. | key | default | meaning |
  122. |---|---|---|
  123. | `title`, `author` | from the book | metadata of the translated book |
  124. | `engine`, `model`, `reasoning` | `codex`, —, `low` | translation engine (`codex`, `claude`, or `command` with `engine_command`) |
  125. | `review_engine`, `review_model`, `review_reasoning` | same as translation, —, `medium` | review engine |
  126. | `review` | `full` | `full`, `flagged` (only parts with problems) or `none` |
  127. | `group_size`, `parallel`, `retries` | 3, 3, 2 | parts per call, calls at once, retries of a rejected part |
  128. | `genre`, `system_boxes` | `fiction`, automatic | genre rules (see Genres); boxed bold-only paragraphs, on for `gamelit` |
  129. | `replacements`, `forbidden`, `uppercase_chat` | from the language profile | automatic fixes, blocking forms, all-caps chat names |
  130. | `formats` | `epub,docx,pdf` | output formats |
  131. The per-book style rules live in `rules.md`, and the glossary in `terms.json`.
  132. ## Repository layout
  133. ```
  134. skills/book-translate-lite/ the skill: SKILL.md, scripts/ (btl.py and the pipeline), templates/
  135. .claude-plugin/ .codex-plugin/ .agents/ plugin and marketplace manifests
  136. docs/ tests/ install.sh
  137. ```
  138. Tests run without any model, using a fake engine and a short book written for them:
  139. ```bash
  140. python3 tests/test_all.py
  141. ```
  142. ## Notes
  143. - Translate only books you have the right to translate, for example for personal use or with permission.
  144. ## License
  145. MIT. `skills/book-translate-lite/scripts/vendor/convert.py` and `manifest.py`, which handle input conversion and splitting, are copied unchanged from **translate-book** © 2025 Rainman (MIT); see `scripts/vendor/LICENSE-translate-book`. Everything else was written from scratch.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.