Revayat-Novel-Skill

Revayat Novel — روایت

Translate a whole book into publication-quality Persian, and get a Word file a publisher could work from.

An agent skill for Claude Code, Kiro, Codex, Cursor, Cline and any other coding agent that can read a SKILL.md. It handles the parts that make book translation actually hard: scanned pages, illustrations that must keep their size and place, names that must not drift across forty chapters, and Persian typography that has to be right rather than approximately right.

Web novels can start from a website link or ordered saved HTML/text chapters; the bundled intake workflow preserves source snapshots and resumes without overwriting translated work. Native DOCX/PDF book guidance ships inside the skill. Optional parallel translation and editing asks the user first; one coordinator keeps terminology, integration and QA consistent.

EPUB imports refuse missing chapters, pictures and unresolved explicit notes; recovery guidance explains how to repair the source without deleting content. The opt-in audit replay workflow retains tracked-source ZIP, complete reachable HEAD history bundle and SHA-256 checksums. Its artifact includes audit-export_YYYY-MM-DD_HH-mm-ss_UTC.log with UTC INFO/DEBUG/WARNING/ERROR export events, no credentials or book content; artifacts expire after seven days. Verify checksums before replaying.

The separate offline sandbox CI requires isolation proof before a finite synthetic parser/transaction corpus. It is not a complete security audit or literary certification.

What it does that a generic translator does not

Install

git clone https://github.com/KiaroSama/Revayat-Novel-Skill.git
cd Revayat-Novel-Skill
pip install -r skills/revayat-novel/requirements.txt

Then install the skill into whichever agents you use:

# macOS / Linux
./install/install.sh

# Windows
powershell -ExecutionPolicy Bypass -File .\install\install.ps1

By default this installs into every agent it finds — Claude Code, Kiro, Codex, Cursor, Cline, Hermes, OpenCode and Antigravity. OpenCode and Antigravity also get an AGENTS.md pointer, because that is how they discover instructions. Use --agent claude for one, and --scope project --path <dir> for a single project. Both wrappers require Python 3.10+ before installation and use one standard-library engine. Updating an existing copy requires --force / -Force in automation; interactive confirmation defaults to No, including EOF.

Installation verifies the complete selected payload before replacing any copy. Old copies and instruction files are retained in a protected local state area; the next invocation recovers an interrupted transaction or refuses conflicting edits. Only the owned AGENTS.md section changes; surrounding bytes remain exact. See installer safety and recovery for logs, retained backups, inventory maintenance and the limits of multi-directory recovery.

As a Claude Code plugin

/plugin marketplace add KiaroSama/Revayat-Novel-Skill
/plugin install revayat-novel@KiaroSama/Revayat-Novel-Skill

That also gives you /translate-book, /revayat-novel-resume and /revayat-novel-qa.

Check the install

Python 3.10 or newer, on Linux, macOS or Windows. CI runs 3.10, 3.13 and 3.14 on all three. Note that 3.10 reaches end of life in October 2026 — it still works here, and it stops receiving CPython security fixes.

python skills/revayat-novel/scripts/revayat-novel.py doctor

Optional. skills/revayat-novel/requirements-optional.txt declares the two wheels two stages need — ocrmypdf for scanned or mixed PDFs, and pywin32 for the Word render path on Windows. Nothing else needs them, and doctor reports which are present.

pip install -r skills/revayat-novel/requirements-optional.txt

# Tesseract (the OCR engine):
winget install tesseract-ocr.tesseract     # Windows
brew install tesseract                     # macOS
sudo apt install tesseract-ocr             # Debian/Ubuntu

# Ghostscript — not carried by winget; download the installer:
#   https://ghostscript.com/releases/gsdnld.html
brew install ghostscript                   # macOS
sudo apt install ghostscript               # Debian/Ubuntu

None of them has to be on PATH. doctor looks on PATH, then in the script directory of the interpreter you ran pip install with — a virtual environment usually is not on PATH — and then where each installer leaves the tool.

Integrity and review limits

Native intake retains authored tables (including empty/nested grids), control-only layout, applicable complex-script emphasis and every actual PDF image occurrence. Unsupported geometry refuses instead of silently rewriting assets. Page acceptance rechecks live glossary/context dependencies; complete current raster evidence is required for visual approval. OCR caches carry source/output-bound coverage proofs; ambiguous silent raster roles need an explicit --ocr-page-roles manifest. Approved image-role pages retain artwork even when OCR recognizes a caption; ambiguous retained page rasters are preserved and reported during MinerU placement.

The installer supports read-only --status (-Status in PowerShell); it observes stable receipts but does not claim OS-lock exclusivity. Evaluation's adjudication protocol prepares all 28 cases as pending and validates independent result intake—no human literary approval is invented. CI may retain only bounded, allowlisted synthetic failure evidence, never real books.

Use

Ask your agent, in whatever words you like:

Translate book.pdf into Persian and give me a Word file.

Or with the plugin: /translate-book ./book.pdf

The agent asks whether to use parallel subagents, then runs the pipeline and stops at the points where your judgement matters — chiefly the glossary, where you decide what each character is called in Persian.

Or drive it yourself

S=skills/revayat-novel/scripts
# $PY is the interpreter you have: python3 on macOS/Linux, python or py -3 on
# Windows, where python3 usually does not exist.

$PY $S/revayat-novel.py extract book.pdf --out work/
$PY $S/revayat-novel.py glossary scan --book work/book.json --out work/glossary.json
#   … fill in the Persian names in work/glossary.json …

# A PDF is cut by page — one job per source page, so each one can be checked
# against the page it came from. EPUB, DOCX and plain text have no pages, and
# take `chunk build --out work/chunks` instead.
$PY $S/revayat-novel.py pages build --book work/book.json --out work/pages --glossary work/glossary.json

# then, per page: translate work/pages/pageNNNN.md -> out_pageNNNN.md, and
$PY $S/revayat-novel.py pages     merge   --book work/book.json --pages work/pages --page 1 --glossary work/glossary.json
$PY $S/revayat-novel.py render-qa --book work/book.json --work work --page 1
#   … look at renders/source/page-0001.png beside renders/target/page-0001.png …
$PY $S/revayat-novel.py pages     review  --pages work/pages --page 1 --answer …
$PY $S/revayat-novel.py pages     accept  --book work/book.json --pages work/pages --page 1

# Finish the published text *before* anybody reads it: typography is mechanical
# and the title page is published prose. Both move the revision the approvals
# below are bound to, so running them afterwards makes those approvals stale.
#   … set meta.title_target / meta.author_target through bookwrite.transaction …
$PY $S/revayat-novel.py falint fix --book work/book.json

# Read the Persian against the English. Three rubrics are about meaning and
# block; two are about style and deliberately do not.
$PY $S/revayat-novel.py meaning sheets --book work/book.json --out work/review
#   … read work/review/sheet_NNNN.md, write findings to out_sheet_NNNN.md …
$PY $S/revayat-novel.py meaning record --book work/book.json --out work/review
$PY $S/revayat-novel.py meaning status --book work/book.json --out work/review

# An independent Persian reading complements the source-grounded review.
$PY $S/revayat-novel.py fluency sheets --book work/book.json --out work/fluency --meaning work/review
#   … read work/fluency/sheet_NNNN.md, propose replacements in out_sheet_NNNN.md …
$PY $S/revayat-novel.py fluency record --book work/book.json --out work/fluency
$PY $S/revayat-novel.py fluency apply  --book work/book.json --out work/fluency
#   … the book moved, so repeat the complete `meaning` review above: that re-run
#       is the comparison against the source, and nothing passes without it …
$PY $S/revayat-novel.py fluency status --book work/book.json --out work/fluency --meaning work/review

# Nothing left for typography to fix, or the approvals above describe older text.
$PY $S/revayat-novel.py falint lint  --book work/book.json
# `--review` and `--fluency` are how the two semantic verdicts are enforced here;
# without them the report says `semantic-unverified`, which `--strict` blocks on.
$PY $S/revayat-novel.py qa check --book work/book.json --assets work/assets \
  --glossary work/glossary.json --review work/review --fluency work/fluency --strict
$PY $S/revayat-novel.py build  --book work/book.json --out out/book.fa.docx --font "Vazir"

# Two final gates, and the file is not ready until both pass: the package, and
# the finished book rendered and looked at.
$PY $S/revayat-novel.py qa     docx  --file out/book.fa.docx --book work/book.json
$PY $S/revayat-novel.py doc-qa check --book work/book.json --work work --docx out/book.fa.docx
$PY $S/revayat-novel.py doc-qa review --work work --answer …
$PY $S/revayat-novel.py doc-qa check --book work/book.json --work work --docx out/book.fa.docx

How it works

book.pdf / .epub / .docx
        │
        ▼  probe every page: digital · scanned · mixed
   OCRmyPDF ──────── only the pages that need it, images untouched
        │
        ▼
   Book IR  ── blocks, runs, image bytes + geometry, footnotes, page setup
        │      (book.json — the source of truth; Markdown deliberately is not)
        ├──────────────▶ glossary.json ── locked names, aliases, character voices
        ▼
   chapter-aware worksheets ── term table + neighbouring context per chunk
        │
        ▼  translated serially, or in parallel with user consent
   merge ── every @@ id must return exactly once, or it is a named error
        │
        ▼
   metadata + Persian typography ── settle the published text first
        ▼
   bilingual review → independent Persian review → renewed source confirmation
        │
        ▼
   quality gates ── coverage, footnote parity, omissions, image hashes, glossary
        │
        ▼
   build ── python-docx + raw OOXML for footnotes, bookmarks, TOC, bidi
        │
        ▼
   book.fa.docx  +  package-level verification

The Book IR is the design decision everything else follows from. Routing a book through Markdown loses image geometry, footnote identity and page setup, and then no amount of care downstream can get them back. Only inline emphasis travels as markup — because models handle *italic* far more reliably than a bespoke XML dialect, and because QA can verify it by counting.

What it is honest about

Word reflows. A Persian paragraph is rarely the same length as its English original, so an editable document cannot also be page-for-page identical to the source PDF. Any tool promising both is producing uneditable text boxes.

What is exact: image bytes, physical size and aspect; where each picture sits in the text; heading hierarchy and chapter breaks; bold and italic; footnote placement and numbering — and endnotes, folded in as footnotes; the source's section breaks and their page geometry; hyperlink targets, rebuilt as live links wherever the translation kept the display phrase; the running heads, carried across in Persian; chapter links; and selectable, searchable, editable Persian.

Two more limits worth knowing up front:

• PDF heading detection is a font-size heuristic. On an unusual design it misses; fix the levels in book.json before chunking, or use MinerU.
• In a scanned book an illustration is usually part of the page raster rather than a separate image object, so there is nothing to extract. MinerU's layout model finds those; --from-mineru imports its output.
• doc-qa check --keep-pdf will hand you a PDF of the finished book, with the Persian selectable and the font embedded. Its contents page is text rather than a clickable PDF outline, and its pagination is the rendering program's — the .docx remains the editable deliverable.

Documentation

The skill loads these on demand rather than up front:

• translation-policy.md — what a faithful literary translation requires
• persian-typography.md — RTL, ZWNJ, punctuation, mixed scripts
• extraction.md — OCR routing, difficult books, the IR schema
• watermarks.md — removing a colour stamp from a scan, and what it cannot do
• glossary-and-voice.md — naming policy, aliases, character voice
• docx-and-ooxml.md — every build option and what Word structure it produces
• troubleshooting.md — the failures you are most likely to hit

Development

pip install -r skills/revayat-novel/requirements.txt
python -m pytest tests -q

Fixtures are generated, not committed: the suite builds its own PDF, EPUB and DOCX, so it stays fast and no third-party book text is vendored in.

tests/e2e_pipeline.py runs every stage against a generated book — extract, glossary, chunk, merge, typography, semantic reviews, QA, build, package verification — so a break in the seam between two stages fails even when each module's own tests pass. CI runs it on Linux, macOS and Windows.

python tests/run_audit.py --repo . runs normal collection including the shared contract regressions, retaining JUnit and a result record under .pytest-tmp/audit/. Reviewer replies in those fixtures simulate protocol states; they do not certify linguistic quality. The original benchmark accepts multiple faithful renderings and reports unseen ones as unknown, without an overall quality score.

See review-contracts.md for explicit approval states, immutable reply archives, retryable freshness refusals and legacy migration. An empty edit list or unknown digest never approves delivery. Every agent using the skill must keep a UTF-8 workflow log beside the translated file, recording translation, corrections and verification. The preservation rules also require original page dimensions, original image resolution and documented, visually checked derivatives when poor images need improvement. Source-language profiles cover Japanese, Korean, Chinese, French, Spanish and English to Persian, with evidence and uncertainty rules rather than claims of automatic literary quality.

Credits

The orchestration shape — chunking a book, translating chunks in parallel sub-agents with a shared glossary, and resuming a partial run — follows the approach demonstrated by deusyu/translate-book (MIT). Extraction and OCR routing build on PyMuPDF, OCRmyPDF and, optionally, MinerU. The intermediate-representation approach to preserving layout through translation is the idea behind BabelDOC.

Donate

If this project helps you, donations are appreciated.

Author

Author: Kiaro Sama GitHub: https://github.com/KiaroSama

License

GNU General Public License v3.0 or later.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the licence for details.