Revayat — Traducción de libros inglés → persa
Ejecute los nueve pasos siguientes en orden. Cada uno es un comando con una regla sobre qué hacer con su salida. No improvise un orden diferente y no omita un paso porque el anterior se vea bien.
Defina dos variables una vez y utilícelas en todas partes:
SKILL_DIR— la carpeta que contiene este archivo. En un plugin de Claude Code es${CLAUDE_PLUGIN_ROOT}/skills/revayat.WORK— una carpeta de trabajo para este libro, p. ej.work/.
Cada comando es python3 $SKILL_DIR/scripts/revayat.py <etapa> ….
Las cinco reglas que nunca deben romperse
- Nunca invierta el texto persa para que se lea de derecha a izquierda. La dirección la establece el generador. Invertir produce un archivo que funciona en todos lados excepto en un visor.
- Nunca invente, elimine, fusione, divida o reordene un encabezado
@@ id. Devuelva exactamente los que le fueron dados. - Nunca elimine un marcador
[[fn:…]],**bold**,*italic*o`verbatim`. Se cuentan; un desajuste falla el control de calidad. - Nunca edite manualmente
book.jsonpara corregir una traducción. Corrija la hoja de trabajo y vuelva a ejecutar la fusión. - Nunca acorte el libro. No resuma, no omita una frase difícil, no suavice. Si un paso informa contenido faltante, vuelva a ejecutar ese fragmento.
Paso 1 — Verificar las herramientas
python3 $SKILL_DIR/scripts/revayat.py doctor
"ready": true→ continúe."ready": false→ ejecutepip install -r $SKILL_DIR/requirements.txt, luego ejecutedoctorde nuevo.optional_toolsque muestrenot foundestá bien por ahora. El paso 2 le indicará si realmente se necesita OCR.
Paso 2 — Extraer
python3 $SKILL_DIR/scripts/revayat.py extract "<archivo de entrada>" --out $WORK
Para una fuente en persa, agregue --ocr-lang fas. Para otros idiomas use el código Tesseract (deu, fra, ara, …).
Lea el JSON que imprime y siga la tabla:
| Lo que ve | Qué hacer |
|---|---|
"kind": "digital" | nada; no se necesitó OCR |
"kind": "scanned" o "mixed" | el OCR se ejecutó automáticamente; verifique que ocr.probe_after.text_share esté por encima de 0.7 |
| un error que nombre a OCRmyPDF | instálelo como dice el mensaje, luego vuelva a ejecutar este paso |
clean_scan.cleaned por encima de 0 | se eliminó una marca de agua de color de esa cantidad de páginas |
ocr.warning no es nulo | léalo; el archivo aún era utilizable, así que continúe |
page_scans_dropped por encima de 0 | esa cantidad de rasterizaciones de página completa se reconocieron como el escaneo en sí, no como imágenes |
El limpiador nunca edita su archivo: el original permanece intacto y la copia limpia se escribe en $WORK/cleaned.pdf, con un registro por página en clean_scan de lo que se eliminó y lo que se dejó. Pase --clean-scan off para omitirlo por completo, o --clean-scan force cuando una marca de agua haya sobrevivido.
Si el libro fue escaneado, haga estas dos pasadas adicionales ahora.
Confianza de reconocimiento — sin ella, una palabra mal leída es indistinguible de una correcta, porque ambas son persa fluido:
python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json
Esto escribe source.ocr.json (por palabra, línea, bloque y página: cuadro, confianza, orden de lectura y qué preprocesamiento se ejecutó) y source.ocr.txt, luego sella cada bloque en book.json con la confianza de la región de la que provino. Los bloques calificados como low son informados por qa check como ocr-low-confidence, y aceptar uno significa mirar la imagen de la página. Los umbrales predeterminados son 85 y 60 y se mueven con --high / --low.
Ilustraciones dentro de un escaneo — una página escaneada es una imagen plana, por lo que una fotografía en ella no es una imagen separada hasta que algo la encuentre:
mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<archivo de entrada>" --out $WORK --figures-from-mineru $WORK/mineru
Ejecute MinerU en cleaned.pdf, no en el original, o recortará la marca de agua como si fuera una figura. Tome solo las imágenes de MinerU. Su propio texto reconocido para persa regresa con las palabras y las letras dentro de ellas invertidas; Tesseract con fas lee la misma página correctamente, por lo que el texto permanece donde está. Use --figures-page-offset N cuando MinerU se haya ejecutado sobre un rango de páginas.
Luego mire el resultado antes de continuar:
python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete
Ignore untranslated-block aquí — nada está traducido todavía. Está buscando asset-missing. Si stats.text_blocks está por debajo de 20 para un libro real, la extracción falló: consulte references/extraction.md.
Paso 3 — Glosario
python3 $SKILL_DIR/scripts/revayat.py glossary scan \
--book $WORK/book.json --out $WORK/glossary.json
El informe enumera needs_persian, primero los más frecuentes. Abra $WORK/glossary.json y para cada una de las primeras 20 entradas complete cuatro campos:
"target": "الیزابت بنت",
"later_form": "الیزابت بنت",
"first_form": "الیزابت بنت (Elizabeth Bennet)",
"locked": true
Deje first_block_id exactamente como está — el pipeline lo usa para decidir qué fragmento único introduce el nombre. No lo edite y no decida las primeras menciones usted mismo.
Elimine las entradas que no sean nombres reales. Luego continúe.
Paso 4 — Fragmentar
python3 $SKILL_DIR/scripts/revayat.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
Observe el número de fragmentos. Cada uno se convierte en una tarea de traducción.
Si ya ha traducido algunas hojas de trabajo y una entrada ha cambiado desde entonces, esto se niega con "refused": "stale-worksheets" en lugar de entregarle silenciosamente hojas de trabajo que ya no coinciden con el libro. Vuelva a leer la razón que da; agregue --force solo una vez que haya decidido que las traducciones existentes siguen siendo buenas.
Paso 5 — Traducir
Para cada $WORK/chunks/chunkNNNN.md, produzca $WORK/chunks/out_chunkNNNN.md. Use un subagente separado por fragmento cuando su tiempo de ejecución los tenga, 8 a la vez. Si no es así, hágalos uno a uno — el resultado es el mismo, solo más lento.
Déle al subagente exactamente esto:
Lea
$WORK/chunks/chunkNNNN.mdy escriba$WORK/chunks/out_chunkNNNN.md.Traduzca al persa. Lea primero
$SKILL_DIR/references/translation-policy.mdy sígalo.Formato de salida — esto es mecánico, hágalo exactamente correcto:
- Copie cada línea
@@ <id> <kind>sin cambios, en el mismo orden.- Ponga la traducción al persa en las líneas debajo.
- No genere nada más: sin preámbulo, sin inglés, sin comentarios, sin resumen.
Reglas:
- La tabla "Nombres" es vinculante. Cuando una fila dice "primera mención, preséntela aquí", use esa forma más larga. En cualquier otro lugar use la forma corta. No decida esto usted mismo — la tabla ya lo hizo.
- "Texto circundante" es solo contexto. Nunca lo traduzca ni lo copie.
- Mantenga
**bold**,*italic*,`verbatim`y[[fn:…]]exactamente, alrededor de las palabras persas equivalentes. No agregue ni elimine ninguno.- Traduzca cada unidad completamente. Nunca resuma ni omita.
- Para agregar su propia nota al pie: escriba
[[fn:tr-01]]en la oración y agregue un bloque@@ tr-01 footnoteal final con su texto. Solo para una referencia cultural genuina o un juego de palabras.
Verifique lo que queda en cualquier momento:
python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks
Paso 6 — Fusionar
python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks
| Campo | Significado | Acción |
|---|---|---|
"ok": true | todo aterrizó | continúe al paso 7 |
missing_outputs | esos fragmentos nunca se tradujeron | tradúzcalos |
missing_units | se eliminaron encabezados | vuelva a ejecutar esos fragmentos |
unknown_units | se inventaron encabezados | vuelva a ejecutar esos fragmentos |
Volver a ejecutar la fusión después de una corrección siempre es seguro.
Paso 7 — Tipografía persa
python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json
Solo mecánico y seguro de ejecutar dos veces. Agregue --digits keep si el libro debe mantener los numerales latinos.
Paso 8 — Validar, luego construir
python3 $SKILL_DIR/scripts/revayat.py qa check \
--book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json
No construya mientras "ok" sea falso. Corrija según el código de error:
| Código | Significado | Acción |
|---|---|---|
untranslated-block | un bloque no tiene persa | traduzca ese fragmento |
footnote-marker-lost | se eliminó un [[fn:…]] | vuelva a ejecutar ese fragmento |
footnote-marker-invented | un marcador apunta a nada | vuelva a ejecutar ese fragmento |
possible-omission | texto destino mucho más corto que la fuente | léalo; generalmente una cláusula eliminada |
untranslated | inglés dejado en el persa | vuelva a ejecutar ese fragmento |
asset-missing / asset-modified | una imagen falta o está alterada | vuelva a extraer |
copied-source-run | una cláusula de la fuente está viva dentro del persa | vuelva a ejecutar ese fragmento |
duplicate-translation | dos fuentes diferentes obtuvieron el mismo persa | una respuesta de hoja de trabajo se pegó dos veces; vuelva a ejecutar ambas |
first-mention-repeated | un nombre se introduce en más de un lugar | mantenga el primero, elimine el resto |
image-order | las imágenes están en el orden incorrecto en el paquete | vuelva a construir |
bookmarks-missing / bookmark-duplicate | la TOC no enlazaría a ningún lado, o al lugar equivocado | vuelva a construir |
emphasis-parity (advertencia) | el conteo de negrita/cursiva cambió | verifique uno; a menudo está bien |
glossary-drift (advertencia) | un nombre bloqueado se representó de manera diferente | vuelva a ejecutar ese fragmento |
ocr-low-confidence (advertencia) | el motor no estaba seguro de este bloque | abra la imagen de la página y compare |
Agregue --strict para que los últimos tres también sean bloqueantes, para trabajo de publicación.
Traduzca el título y el autor del libro a meta.title_target y meta.author_target en book.json — esa es la única edición manual que se espera, porque no hay una hoja de trabajo para ellos.
Luego construya:
python3 $SKILL_DIR/scripts/revayat.py build \
--book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
--font "Vazirmatn" --size 11.5
Banderas útiles: --font Tahoma cuando el archivo debe renderizarse en una máquina sin fuentes persas; --heading-size source para reproducir los tamaños de punto de los encabezados originales; --template ref.docx para heredar estilos de un archivo Word existente. Lista completa en references/docx-and-ooxml.md.
Paso 9 — Verificar e informar
python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json
Si "ok": false, corríjalo antes de decirle al usuario que el archivo está listo.
Luego informe: dónde está el archivo, cuántos capítulos, imágenes y notas al pie tiene, cualquier cosa que el control de calidad haya marcado y que haya decidido no abordar, y esta limitación:
Word reajusta el texto, por lo que un documento persa editable no puede ser idéntico página por página al PDF de origen. Los bytes de imagen y el tamaño físico, la estructura de capítulos, el énfasis, las notas al pie y los enlaces de capítulos son exactos.
Referencias
Lea estas solo cuando el paso las señale:
references/translation-policy.md— qué darle al subagente traductorreferences/persian-typography.md— RTL, ZWNJ, puntuación, scripts mixtosreferences/extraction.md— enrutamiento de OCR, marcas de agua, libros difícilesreferences/glossary-and-voice.md— política de nomenclatura, alias, voz de personajesreferences/docx-and-ooxml.md— cada opción de construcción y qué producereferences/troubleshooting.md— las fallas que es más probable que encuentre