Revayat — Traduction anglais → persan
Exécutez les neuf étapes ci-dessous dans l'ordre. Chacune est une commande plus une règle sur ce qu'il faut faire avec son résultat. N'improvisez pas un ordre différent et ne sautez pas une étape parce que la précédente semblait correcte.
Définissez deux variables une fois, puis utilisez-les partout :
SKILL_DIR— le dossier contenant ce fichier. Dans un plugin Claude Code, il s'agit de${CLAUDE_PLUGIN_ROOT}/skills/revayat.WORK— un dossier de travail pour ce livre, par ex.work/.
Chaque commande est python3 $SKILL_DIR/scripts/revayat.py <étape> ….
Les cinq règles qui ne doivent jamais être enfreintes
- N'inversez jamais le texte persan pour le faire lire de droite à gauche. La direction est définie par le générateur. L'inversion produit un fichier qui est cassé partout sauf dans un seul visualiseur.
- N'inventez, ne supprimez, ne fusionnez, ne divisez et ne réordonnez jamais un en-tête
@@ id. Renvoyez exactement ceux que vous avez reçus. - Ne supprimez jamais un marqueur
[[fn:…]],**gras**,*italique*ou`verbeux`. Ils sont comptés ; une discordance échoue au QA. - Ne modifiez jamais manuellement
book.jsonpour corriger une traduction. Corrigez la feuille de travail et relancez la fusion. - Ne raccourcissez jamais le livre. Pas de résumé, pas de saut d'une phrase difficile, pas d'atténuation. Si une étape signale un contenu manquant, relancez ce morceau.
Étape 1 — Vérifier les outils
python3 $SKILL_DIR/scripts/revayat.py doctor
"ready": true→ continuez."ready": false→ exécutezpip install -r $SKILL_DIR/requirements.txt, puis relancezdoctor.- Si
optional_toolsaffichenot found, ce n'est pas grave pour l'instant. L'étape 2 vous dira si l'OCR est réellement nécessaire.
Étape 2 — Extraire
python3 $SKILL_DIR/scripts/revayat.py extract "<fichier d'entrée>" --out $WORK
Pour une source en persan, ajoutez --ocr-lang fas. Pour d'autres langues, utilisez le code Tesseract (deu, fra, ara, …).
Lisez le JSON qu'il affiche et suivez le tableau :
| Ce que vous voyez | Ce qu'il faut faire |
|---|---|
"kind": "digital" | rien ; aucune OCR n'était nécessaire |
"kind": "scanned" ou "mixed" | L'OCR s'est exécutée automatiquement ; vérifiez que ocr.probe_after.text_share est supérieur à 0.7 |
| une erreur nommant OCRmyPDF | installez-la comme indiqué dans le message, puis relancez cette étape |
clean_scan.cleaned supérieur à 0 | un filigrane couleur a été supprimé de ce nombre de pages |
ocr.warning n'est pas nul | lisez-le ; le fichier était toujours utilisable, continuez donc |
page_scans_dropped supérieur à 0 | autant de rasters pleine page ont été reconnus comme le scan lui-même, et non comme des images |
Le nettoyeur ne modifie jamais votre fichier : l'original reste intact et la copie nettoyée est écrite dans $WORK/cleaned.pdf, avec un enregistrement page par page dans clean_scan de ce qui a été supprimé et de ce qui a été laissé. Passez --clean-scan off pour l'ignorer complètement, ou --clean-scan force lorsqu'un tampon a survécu.
Si le livre a été scanné, effectuez ces deux passages supplémentaires maintenant.
Confiance de reconnaissance — sans elle, un mot mal lu est impossible à distinguer d'un mot correct, car les deux sont en persan courant :
python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json
Ceci écrit source.ocr.json (par mot, ligne, bloc et page : boîte, confiance, ordre de lecture et quel prétraitement a été exécuté) et source.ocr.txt, puis estampe chaque bloc dans book.json avec la confiance de la région d'où il provient. Les blocs notés low sont signalés par qa check comme ocr-low-confidence, et en accepter un signifie regarder l'image de la page. Les seuils par défaut sont 85 et 60 et se déplacent avec --high / --low.
Illustrations à l'intérieur d'un scan — une page scannée est une seule image plane, donc une photographie sur cette page n'est pas une image séparée tant que quelque chose ne la trouve pas :
mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<fichier d'entrée>" --out $WORK --figures-from-mineru $WORK/mineru
Exécutez MinerU sur cleaned.pdf, pas sur l'original, sinon il recadre le filigrane comme s'il s'agissait d'une figure. Ne prenez que les images de MinerU. Son propre texte reconnu pour le persan revient avec les mots et les lettres à l'intérieur inversés ; Tesseract avec fas lit la même page correctement, donc le texte reste là où il est. Utilisez --figures-page-offset N lorsque MinerU a été exécuté sur une plage de pages.
Ensuite, regardez le résultat avant d'aller plus loin :
python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete
Ignorez untranslated-block ici — rien n'est encore traduit. Vous recherchez asset-missing. Si stats.text_blocks est inférieur à 20 pour un vrai livre, l'extraction a échoué : voir references/extraction.md.
Étape 3 — Glossaire
python3 $SKILL_DIR/scripts/revayat.py glossary scan \
--book $WORK/book.json --out $WORK/glossary.json
Le rapport liste les needs_persian, les plus fréquents en premier. Ouvrez $WORK/glossary.json et pour chacune des 20 premières entrées, remplissez quatre champs :
"target": "الیزابت بنت",
"later_form": "الیزابت بنت",
"first_form": "الیزابت بنت (Elizabeth Bennet)",
"locked": true
Laissez first_block_id exactement comme il est — le pipeline l'utilise pour décider quel bloc unique présente le nom. Ne le modifiez pas et ne décidez pas vous-même des premières mentions.
Supprimez les entrées qui ne sont pas de vrais noms. Continuez ensuite.
Étape 4 — Découpage
python3 $SKILL_DIR/scripts/revayat.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
Notez le nombre de chunks. Chacun devient une tâche de traduction.
Si vous avez déjà traduit des feuilles de travail et qu'une entrée a changé depuis, cela refuse avec "refused": "stale-worksheets" plutôt que de vous remettre silencieusement des feuilles de travail qui ne correspondent plus au livre. Re-lisez la raison donnée ; ajoutez --force uniquement après avoir décidé que les traductions existantes sont toujours bonnes.
Étape 5 — Traduire
Pour chaque $WORK/chunks/chunkNNNN.md, produisez $WORK/chunks/out_chunkNNNN.md. Utilisez un sous-agent séparé par chunk lorsque votre environnement d'exécution le permet, 8 à la fois. Sinon, faites-les un par un — le résultat est le même, seulement plus lent.
Donnez exactement ceci au sous-agent :
Lisez
$WORK/chunks/chunkNNNN.mdet écrivez$WORK/chunks/out_chunkNNNN.md.Traduisez en persan. Lisez d'abord
$SKILL_DIR/references/translation-policy.mdet suivez-le.Format de sortie — c'est mécanique, faites-le exactement correct :
- Copiez chaque ligne
@@ <id> <kind>inchangée, dans le même ordre.- Mettez la traduction persane sur les lignes en dessous.
- Ne produisez rien d'autre : pas de préambule, pas d'anglais, pas de commentaire, pas de résumé.
Règles :
- Le tableau "Noms" est contraignant. Lorsqu'une ligne dit "première mention, introduisez-le ici", utilisez cette forme longue. Partout ailleurs, utilisez la forme courte. Ne décidez pas cela vous-même — le tableau l'a déjà fait.
- "Texte environnant" n'est que du contexte. Ne le traduisez jamais et ne le copiez pas.
- Conservez
**gras**,*italique*,`verbeux`et[[fn:…]]exactement, autour des mots persans équivalents. N'en ajoutez pas et n'en supprimez pas.- Traduisez chaque unité complètement. Ne résumez jamais et ne sautez rien.
- Pour ajouter votre propre note de bas de page : écrivez
[[fn:tr-01]]dans la phrase et ajoutez un bloc@@ tr-01 footnoteà la fin avec son texte. Uniquement pour une véritable référence culturelle ou un jeu de mots.
Vérifiez ce qu'il reste à tout moment :
python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks
Étape 6 — Fusion
python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks
| Champ | Signification | Action |
|---|---|---|
"ok": true | tout a atterri | continuez à l'étape 7 |
missing_outputs | ces chunks n'ont jamais été traduits | traduisez-les |
missing_units | des en-têtes ont été supprimés | relancez ces chunks |
unknown_units | des en-têtes ont été inventés | relancez ces chunks |
Relancer la fusion après une correction est toujours sûr.
Étape 7 — Typographie persane
python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json
Mécanique uniquement, et sûr à exécuter deux fois. Ajoutez --digits keep si le livre doit conserver les chiffres latins.
Étape 8 — Contrôle qualité, puis construction
python3 $SKILL_DIR/scripts/revayat.py qa check \
--book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json
Ne construisez pas tant que "ok" est faux. Corrigez par code d'erreur :
| Code | Signification | Action |
|---|---|---|
untranslated-block | un bloc n'a pas de persan | traduisez ce chunk |
footnote-marker-lost | un [[fn:…]] a été supprimé | relancez ce chunk |
footnote-marker-invented | un marqueur pointe vers rien | relancez ce chunk |
possible-omission | la cible est bien plus courte que la source | lisez-la ; généralement une clause supprimée |
untranslated | de l'anglais est resté dans le persan | relancez ce chunk |
asset-missing / asset-modified | une image a disparu ou a été modifiée | réextrayez |
copied-source-run | une clause de la source est vivante dans le persan | relancez ce chunk |
duplicate-translation | deux sources différentes ont obtenu le même persan | une réponse de feuille de travail a été collée deux fois ; relancez les deux |
first-mention-repeated | un nom est introduit à plus d'un endroit | gardez la première, supprimez les autres |
image-order | les images sont dans le mauvais ordre dans le paquet | reconstruisez |
bookmarks-missing / bookmark-duplicate | le sommaire ne mènerait nulle part, ou au mauvais endroit | reconstruisez |
emphasis-parity (avertissement) | le nombre de gras/italique a changé | vérifiez-en un ; souvent correct |
glossary-drift (avertissement) | un nom verrouillé a été rendu différemment | relancez ce chunk |
ocr-low-confidence (avertissement) | le moteur n'était pas sûr de ce bloc | ouvrez l'image de la page et comparez |
Ajoutez --strict pour rendre les trois derniers bloquants également, pour un travail de publication.
Traduisez le titre et l'auteur du livre dans meta.title_target et meta.author_target dans book.json — c'est la seule modification manuelle qui est attendue, car il n'y a pas de feuille de travail pour eux.
Ensuite, construisez :
python3 $SKILL_DIR/scripts/revayat.py build \
--book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
--font "Vazirmatn" --size 11.5
Indicateurs utiles : --font Tahoma lorsque le fichier doit s'afficher sur une machine sans polices persanes ; --heading-size source pour reproduire les tailles de points des titres originaux ; --template ref.docx pour hériter des styles d'un fichier Word existant. Liste complète dans references/docx-and-ooxml.md.
Étape 9 — Vérifier et rapporter
python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json
Si "ok": false, corrigez-le avant de dire à l'utilisateur que le fichier est prêt.
Ensuite, rapportez : où se trouve le fichier, combien de chapitres, d'images et de notes de bas de page il contient, tout ce que le QA a signalé et que vous avez choisi de ne pas traiter, et cette limitation —
Word refond le texte, donc un document persan modifiable ne peut pas être page par page identique au PDF source. Les octets et la taille physique des images, la structure des chapitres, l'emphase, les notes de bas de page et les liens de chapitres sont exacts.
Références
Ne lisez celles-ci que lorsque l'étape les indique :
references/translation-policy.md— ce qu'il faut donner au sous-agent de traductionreferences/persian-typography.md— RTL, ZWNJ, ponctuation, écritures mixtesreferences/extraction.md— routage OCR, filigranes, livres difficilesreferences/glossary-and-voice.md— politique de nommage, alias, voix des personnagesreferences/docx-and-ooxml.md— chaque option de construction et ce qu'elle produitreferences/troubleshooting.md— les échecs les plus probables