KiaroSama/Revayat-Novel-Skill

Revayat Novel – Englisch → Persische Buchübersetzung

Führen Sie die neun Schritte unten der Reihe nach aus. Jeder besteht aus einem Befehl und einer Regel, was mit seiner Ausgabe zu tun ist. Ändern Sie die Reihenfolge nicht und überspringen Sie keinen Schritt, weil der vorherige gut aussah.

Setzen Sie vier Variablen einmal und verwenden Sie sie dann überall:

• SKILL_DIR – der Ordner, der diese Datei enthält. In einem Claude Code Plugin ist das ${CLAUDE_PLUGIN_ROOT}/skills/revayat-novel.
• WORK – ein Arbeitsordner für dieses Buch, z. B. work/.
• PY – der Python-Interpreter. Ermitteln Sie ihn einmal; python3 existiert auf den meisten Windows-Installationen nicht, daher funktioniert eine Befehlszeile, die es fest codiert, auf zwei von drei Plattformen:
  • macOS / Linux: PY=python3
  • Windows: PY=python – oder PY="py -3", falls der Launcher installiert ist
  • falls keines läuft, startet doctor in Schritt 1 nicht, das ist das Signal
• OCR_LANG – der Tesseract-Code für die Sprache, die in dem zu übersetzenden Buch gedruckt ist, nicht die Sprache, in die Sie übersetzen. Für den üblichen Englisch → Persisch-Job ist das eng. Eine persische Quelle ist fas; Deutsch deu, Französisch fra, Arabisch ara. Derselbe Wert muss bei jedem OCR-Schritt verwendet werden. Das Erkennen englischer Seiten mit dem persischen Modell liefert selbstbewusst aussehenden Unsinn, der schlimmer ist als eine niedrige Punktzahl, weil nichts nachgelagertes ihn sehen kann.

Jeder Befehl ist $PY $SKILL_DIR/scripts/revayat-novel.py <stage> ….

---

Die fünf Regeln, die niemals gebrochen werden dürfen

1. Kehren Sie persischen Text niemals um, damit er von rechts nach links gelesen wird. Die Richtung wird vom Builder gesetzt. Eine Umkehrung erzeugt eine Datei, die überall bis auf einen Viewer defekt ist.
2. Erfinden, löschen, zusammenführen, teilen oder neu anordnen Sie niemals einen @@ id-Header. Geben Sie genau diejenigen zurück, die Sie erhalten haben.
3. Löschen Sie niemals einen [[fn:…]], **bold**, *italic* oder `verbatim` Marker. Sie werden gezählt; eine Abweichung führt zum QA-Fehler.
4. Bearbeiten Sie book.json niemals von Hand, um eine Übersetzung zu korrigieren. Korrigieren Sie das Arbeitsblatt und führen Sie die Zusammenführung erneut aus.
5. Kürzen Sie das Buch niemals. Keine Zusammenfassung, kein Überspringen eines schwierigen Satzes, keine Abschwächung. Wenn ein Schritt fehlenden Inhalt meldet, führen Sie diesen Abschnitt erneut aus.

---

Schritt 1 – Werkzeuge prüfen

$PY $SKILL_DIR/scripts/revayat-novel.py doctor

• "ready": true → weiter.
• "ready": false → pip install -r $SKILL_DIR/requirements.txt ausführen, dann doctor erneut ausführen.
• optional_tools mit not found ist für jetzt in Ordnung. Schritt 2 zeigt, ob OCR tatsächlich benötigt wird.

Schritt 2 – Extrahieren

$PY $SKILL_DIR/scripts/revayat-novel.py extract "<input file>" --out $WORK --ocr-lang $OCR_LANG

$OCR_LANG ist die im Buch gedruckte Sprache, die oben einmal gesetzt wurde. Ein Fehler hier ist kein sichtbarer Fehler: OCR gibt trotzdem Text zurück, nur den falschen.

Lesen Sie das JSON, das es ausgibt, und folgen Sie der Tabelle:

Was Sie sehen	Was zu tun ist
"kind": "digital"	nichts; OCR war nicht nötig
"kind": "scanned" oder "mixed"	OCR lief automatisch; prüfen Sie, ob ocr.probe_after.text_share über 0.7 liegt
ein Fehler, der OCRmyPDF nennt	installieren Sie es wie in der Meldung angegeben, dann führen Sie diesen Schritt erneut aus
clean_scan.cleaned über 0	von so vielen Seiten wurde ein Farbwasserzeichen entfernt
ocr.warning ist nicht null	lesen Sie es; die Datei war trotzdem verwendbar, also fahren Sie fort
page_scans_dropped über 0	so viele ganzseitige Raster wurden als der Scan selbst erkannt, nicht als Bilder

Der Reiniger bearbeitet Ihre Datei nie: Das Original bleibt unberührt und die bereinigte Kopie wird in $WORK/cleaned.pdf geschrieben, mit einem seitenweisen Datensatz in clean_scan darüber, was entfernt wurde und was unberührt blieb. Übergeben Sie --clean-scan off, um es ganz zu überspringen, oder --clean-scan force, wenn ein Stempel überlebt hat.

Wenn das Buch gescannt wurde, führen Sie jetzt diese beiden zusätzlichen Durchgänge durch.

Erkennungssicherheit – ohne sie ist ein falsch gelesenes Wort nicht von einem korrekten zu unterscheiden, da beide gewöhnliche Wörter der Quellsprache sind, die in einem grammatikalischen Satz stehen. Nichts später in der Pipeline kann sie unterscheiden, und der Übersetzer wird das falsche Wort getreu wiedergeben.

$PY $SKILL_DIR/scripts/revayat-novel.py ocr-sidecar \
  --pdf $WORK/ocr.pdf --out $WORK --lang $OCR_LANG --book $WORK/book.json

--lang hier ist das gleiche $OCR_LANG, das Sie extract gegeben haben. Es muss sein: Dieser Durchgang erkennt dieselben Seiten erneut, um herauszufinden, wie sicher die Engine war, also liest ein anderes Modell andere Wörter und bewertet etwas, das das Buch nicht sagt.

Dies schreibt source.ocr.json – Kasten, Sicherheit und Lesereihenfolge für jedes Wort, aggregiert bis zu Zeile, Block und Seite, plus welche Vorverarbeitung ausgeführt wurde – und source.ocr.txt, dann stempelt es jeden Block in book.json mit der Sicherheit der Region, aus der er stammt. Blöcke mit der Bewertung low werden von qa check als ocr-low-confidence gemeldet, und einen zu akzeptieren bedeutet, sich das Seitenbild anzusehen. Standardschwellenwerte sind 85 und 60 und verschieben sich mit --high / --low.

Abbildungen in einem Scan – eine gescannte Seite ist ein flaches Bild, daher ist ein Foto darauf kein separates Bild, bis etwas es findet:

mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l en
$PY $SKILL_DIR/scripts/revayat-novel.py extract "<input file>" --out $WORK \
  --figures-from-mineru $WORK/mineru

MinerUs -l verwendet eigene Codes, nicht die von Tesseract: en für eine englische Quelle, arabic für persische oder arabische Schrift. Passen Sie es an das Buch an, genau wie $OCR_LANG angepasst wird – die Layout-Erkennung verwendet die Schrift, um die Seite zu segmentieren.

Führen Sie MinerU auf cleaned.pdf aus, nicht auf dem Original, sonst beschneidet es das Wasserzeichen, als wäre es eine Abbildung. Nehmen Sie nur die Bilder von MinerU. Gemessen an einem echten persischen Scan kamen seine eigenen erkannten Texte mit den Wörtern und den Buchstaben darin umgekehrt zurück, während Tesseract dieselbe Seite korrekt las – der Text kommt also weiterhin vom OCR-Durchlauf oben, und MinerU wird nur für das eine Ding verwendet, das OCR nicht kann, nämlich herauszufinden, wo ein Bild in einem flachen Raster sitzt. Verwenden Sie --figures-page-offset N, wenn MinerU über einen Seitenbereich ausgeführt wurde.

Sehen Sie sich dann das Ergebnis an, bevor Sie fortfahren:

$PY $SKILL_DIR/scripts/revayat-novel.py qa check --book $WORK/book.json --allow-incomplete

Ignorieren Sie hier untranslated-block – noch ist nichts übersetzt. Sie suchen nach asset-missing. Wenn stats.text_blocks für ein echtes Buch unter 20 liegt, ist die Extraktion fehlgeschlagen: siehe references/extraction.md.

Schritt 3 – Glossar

$PY $SKILL_DIR/scripts/revayat-novel.py glossary scan \
  --book $WORK/book.json --out $WORK/glossary.json

Der Bericht listet needs_persian auf, die häufigsten zuerst. Öffnen Sie $WORK/glossary.json und füllen Sie für jeden der ersten 20 Einträge vier Felder aus:

"target":      "الیزابت بنت",
"later_form":  "الیزابت بنت",
"first_form":  "الیزابت بنت (Elizabeth Bennet)",
"locked":      true

Wenn ein Eintrag aliases hat – ein Nachname oder Vorname, den das Buch allein verwendet – setzen Sie deren Persisch in alias_targets:

"aliases":       ["Ashcroft", "Margaret"],
"alias_targets": ["اشکرافت", "مارگارت"]

Wenn die Quelle nur «Ashcroft» sagt, sollte das Persische nur «اشکرافت» sagen. Dies leer zu lassen, führt dazu, dass die Driftprüfung jedes Mal den vollständigen Namen verlangt, was sowohl schlechteres Persisch als auch ein Fehlalarm ist.

Lassen Sie first_block_id genau so, wie es ist – die Pipeline verwendet es, um zu entscheiden, welcher einzelne Abschnitt den Namen einführt. Bearbeiten Sie es nicht und entscheiden Sie nicht selbst über erste Erwähnungen.

Löschen Sie Einträge, die keine echten Namen sind. Fahren Sie dann fort.

Schritt 4 – In Arbeitsblätter aufteilen

Ein ganzer Roman darf niemals in einen Modellkontext gelangen, daher wird er zuerst aufgeteilt. Es gibt zwei Möglichkeiten zum Aufteilen, und die Quelle entscheidet, welche – das ist keine Präferenz:

Quelle	Route
PDF, digital geboren oder gescannt	seitenweise – unten
EPUB, DOCX, reiner Text	nach Zeichenbudget – Schritt 4b

Ein PDF seitenweise aufteilen. Eine Seite ist eine Grenze, die das Buch bereits hat: stabil zwischen Läufen, die Einheit, die ein Prüfer betrachtet, und die einzige Einheit, mit der eine gerenderte Seite verglichen werden kann. Ein nach Zeichenbudget aufgeteiltes Arbeitsblatt bricht dort, wo das Budget ausgeht, was nirgendwo besonders ist – und eine Seite, die in der Quelle nicht existiert, kann nicht gegen die Quelle geprüft werden. Die Formate unter der Linie haben keine eigenen Seiten zum Aufteilen, daher nehmen sie die Budgetroute und geben diese Prüfung auf.

$PY $SKILL_DIR/scripts/revayat-novel.py pages build \
  --book $WORK/book.json --out $WORK/pages --glossary $WORK/glossary.json

Dies schreibt ein Arbeitsblatt pro Quellseite – page0001.md, und seine Übersetzung geht in out_page0001.md daneben. Verwenden Sie diese Namen, nicht die von chunkNNNN.md aus Schritt 5: das Format ist identisch, nur die Dateinamen unterscheiden sich, und pages next sagt Ihnen genau, welche Datei Sie öffnen sollen, also gibt es nichts zu raten.

Es schreibt auch $WORK/pages/source/page-0001.pdf – jede Quellseite als eigenes PDF, kopiert statt neu gerendert, sodass Kästen, Drehung und Bildqualität die des Buches sind. Das Manifest zeichnet jede mit ihrem SHA-256 auf und benennt das reference_pdf, aus dem der gesamte Lauf gelesen wurde. Lesen Sie das Quell-PDF aus dem Manifest; es ist das Original für ein digital geborenes Buch und die OCR-Kopie für einen Scan, und eines von beiden fest zu codieren ist für das andere falsch.

Jeder Seitenjob trägt nur das Nötigste: die Glossarzeilen, die auf dieser Seite gelten, die Stimmen, die dort sprechen, die Wörter, bei denen OCR sich dort unsicher war, und einen begrenzten Ausschnitt der benachbarten Seiten, die als nicht übersetzen markiert sind. Eine Seite, deren eigener Text das Budget überschreitet, wird in nummerierte Teile aufgeteilt, nicht abgeschnitten – part und parts im Manifest geben dies an – und die Teile werden wieder zusammengefügt, bevor die Seite beurteilt wird.

Ein Absatz, den der Seitenumbruch in der Mitte teilt, gehört zu der Seite, auf der er begann, und wird genau einmal übersetzt; die Seite, auf die er läuft, sieht ihn nur als Kontext. Übersetzen Sie niemals einen Block, der unter der Überschrift für Nachbarkontext erscheint – er gehört bereits zum Arbeitsblatt einer anderen Seite.

$PY $SKILL_DIR/scripts/revayat-novel.py pages status --pages $WORK/pages
$PY $SKILL_DIR/scripts/revayat-novel.py pages next   --pages $WORK/pages

status meldet den Zustand jeder Seite; next nennt die erste noch zu erledigende Seite, sodass ein unterbrochener Lauf dort fortgesetzt wird, wo er aufgehört hat, und nicht von Anfang an.

Die Seitenschleife

Das Quell-PDF ist dasjenige, aus dem dieser Lauf gelesen wurde: das eigene PDF des Buches für ein digital geborenes PDF, die OCR-Kopie für einen Scan. Das Manifest hat es aufgezeichnet – nehmen Sie es von dort, anstatt eine Datei zu nennen, die möglicherweise nicht existiert.

SOURCE_PDF=$($PY -c "import json,sys;print(json.load(open(sys.argv[1]))['reference_pdf'])"   $WORK/pages/manifest.json)

Eine Seite nach der anderen, in dieser Reihenfolge. Jeder Befehl benötigt das, was der vorherige produziert hat, daher lehnt ein zu früh ausgeführter Schritt einfach ab:

P=12   # was auch immer `pages next` gerade genannt hat

# 3. die Übersetzung in das Buch einfügen
$PY $SKILL_DIR/scripts/revayat-novel.py pages merge \
  --book $WORK/book.json --pages $WORK/pages --page $P --glossary $WORK/glossary.json

# 4. diese eine Seite allein layouten
$PY $SKILL_DIR/scripts/revayat-novel.py pages preview \
  --book $WORK/book.json --pages $WORK/pages --page $P

# 5. mit der Quellseite vergleichen
$PY $SKILL_DIR/scripts/revayat-novel.py render-qa \
  --book $WORK/book.json --work $WORK --page $P \
  --docx $WORK/previews/page-0012.docx --source-pdf $SOURCE_PDF

# 6. die beiden Bilder ansehen (Schritt 8 sagt, wonach zu suchen ist)
$PY $SKILL_DIR/scripts/revayat-novel.py pages review \
  --pages $WORK/pages --page $P \
  --answer figure-placement=yes --answer script-integrity=yes \
  --answer no-source-language=yes --answer hierarchy=yes \
  --answer reads-as-a-book=yes --note "was Sie gesehen haben"

# 7. erst jetzt
$PY $SKILL_DIR/scripts/revayat-novel.py pages accept \
  --book $WORK/book.json --pages $WORK/pages --page $P

Dann pages next erneut, bis es sagt, dass nichts mehr übrig ist.

Schritt 4 ist nicht optional und Schritt 5 wird es für Sie erledigen, wenn Sie es überspringen – lassen Sie --docx weg und render-qa erstellt die Vorschau selbst. Der explizite Befehl ist für den Fall da, dass Sie die Seite in Word öffnen und selbst ansehen möchten.

Die Vorschau ist eine Quellseite, allein layoutet. Sie ist ausdrücklich nicht das ganze Buch: Persisch fließt um, daher wird Quellseite 12 nicht zur Buchseite 12, und in der Mitte eines Romans beträgt die Drift mehrere Seiten. Die Überprüfung des zwölften Blatts des Buches gegen die Erwartungen von Seite 12 meldet eine korrekte Seite als fehlend mit ihrem gesamten Text und der des Nachbarn. Die Vorschau wird mit dem Produktions-Builder erstellt – gleiche Stile, Schriftarten, RTL, Bildgröße, Überschriftenlogik – daher ist das, was Sie sehen, der echte Satz von echtem Inhalt.

Eine Seite, deren Persisch länger ist als ihr Englisch, wird zu zwei Blättern. Das ist normal, beide werden als renders/target/page-0012.png und page-0012-2.png behalten, und QA liest alle.

accept lehnt ab, es sei denn, jedes Tor ist tatsächlich bestanden – es liest die Beweise, anstatt Ihr Wort zu nehmen, daher kann eine Seite nicht als erledigt markiert werden, indem man behauptet, dass sie es ist. Es möchte vier Dinge: Persisch im Buch für jede Einheit, die die Seite gesendet hat, einen Render-QA-Durchlauf im Laufsprotokoll, einen Bericht, der dies immer noch sagt, und eine aktuelle visuelle Überprüfung.

Die Neuerstellung ist sicher und verwirft nie eine Übersetzung. Eine Seite, deren Quelltext sich seit dem letzten Zuschnitt geändert hat, wird unter invalidated aufgeführt – diese, und nur diese, müssen erneut übersetzt werden. Ein Arbeitsblatt, das von einer Neuerstellung mit einem anderen Budget übrig geblieben ist, wird unter orphaned aufgeführt: Es ist noch auf der Festplatte, wird aber nicht mehr gelesen, daher wird seine Übersetzung das Buch nicht erreichen.

Schritt 4b – Wenn die Quelle keine Seiten hat

Nur EPUB, DOCX und reiner Text. Für ein PDF verwenden Sie Schritt 4.

$PY $SKILL_DIR/scripts/revayat-novel.py chunk build \
  --book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json

Notieren Sie die Anzahl der Abschnitte. Jeder wird zu einer Übersetzungsaufgabe.

Wenn Sie bereits einige Arbeitsblätter übersetzt haben und sich eine Eingabe seitdem geändert hat, lehnt dies mit "refused": "stale-worksheets" ab, anstatt Ihnen stillschweigend Arbeitsblätter zu übergeben, die nicht mehr zum Buch passen. R

…

[für die Übersetzung gekürzt]