Skill d'IA per a la traducció de documents epub

Per tal d'estalviar tokens la propera vegada que necessiti traduïr un llibre, he demanat a Antigravity (Gemini) que em faci una skill amb els scripts que ha generat aquest cop per traduir l'encíclica del papa Lleó.

EPUB Translator Skill

Aquesta skill proporciona un pipeline robust i automatitzat per traduir fitxers de llibres electrònics EPUB de manera professional. Evita problemes de context en dividir el document en petits blocs ordenats (mantenint la integritat del paràgraf) i garanteix la preservació de l'estructura XHTML i els enllaços interns (com ara notes al peu).

Pipeline de Treball

El pipeline es divideix en 4 fases:

1. Preprocessament: Extracció i divisió en blocs lògics.

2. Traducció en paral·lel: Traducció de cada bloc utilitzant subagents.

3. Revisió en paral·lel: Control de qualitat i to lingüístic per subagents revisors.

4. Reconstrucció i verificació: Fusió dels blocs, actualització de metadades, compilació a EPUB/Kindle i validació d'estructures.

-​--

1. Preprocessament

El preprocessament extreu el contingut d'un fitxer XHTML de l'EPUB (per defecte chap_1.xhtml), etiqueta cada element translatable amb un ID seqüencial (elem_N) i genera fitxers JSON per a cadascun dels blocs (chunks) amb un format de context abans/després.

Execució

Utilitza uv run per executar el script de preprocessament:

uv run python /home/pquintana/.gemini/skills/epub-translator/scripts/preprocess.py \

  --epub-path "<ruta_epub_original>" \

  --scratch-dir "<ruta_carpeta_temporal>" \

  --target-file "<nom_fitxer_xhtml_a_l_epub>" \

  --target-chunk-size 100

Aquest procés escriurà els blocs a <ruta_carpeta_temporal>/chunks/chunk_N.json.

-​--

2. Traducció en Paral·lel

Es defineix un subagent traductòleg (translator_agent) amb el següent prompt de sistema (disponible en format plantilla a resources/translator_prompt.txt substituint {SOURCE_LANG} i {TARGET_LANG}):

1. Es llancen subagents per a cadascun dels fitxers chunk_N.json.

2. Cada subagent llegeix el seu chunk, tradueix només el contingut (preservant elements HTML interns com <b>, <i>, <a> i els seus atributs) i genera <ruta_carpeta_temporal>/chunks/translated_chunk_N.json.

-​--

3. Revisió en Paral·lel

Es defineix un subagent revisor (reviewer_agent) amb el prompt de sistema (disponible a resources/reviewer_prompt.txt amb els placeholders corresponents):

1. Es llancen subagents per revisar cada bloc traduït.

2. El revisor compara l'original amb la traducció, valida l'exactitud, ortografia i estil, s'assegura que no es trenquin tags o enllaços, i guarda el text final a la clau revised generant <ruta_carpeta_temporal>/chunks/revised_chunk_N.json.

-​--

4. Reconstrucció i Verificació

Un cop finalitzada la revisió de tots els blocs, s'executa el script de reconstrucció i el de validació.

Reconstrucció

Uneix les traduccions amb la plantilla XHTML original, actualitza l'idioma i les metadades, reconstrueix la taula de continguts (TOC), afegeix l'estil original i genera el nou EPUB. Si ebook-convert (de Calibre) és instal·lat al sistema, també es generaran els formats MOBI i AZW3 automàticament.

uv run python /home/pquintana/.gemini/skills/epub-translator/scripts/reconstruct.py \

  --original-epub "<ruta_epub_original>" \

  --scratch-dir "<ruta_carpeta_temporal>" \

  --output-epub "<ruta_nou_epub>" \

  --target-file "<nom_fitxer_xhtml_a_l_epub>" \

  --title "<nou_títol>" \

  --language "<codi_idioma>" \

  --author "<autor>"

Verificació Estructural

Comprova que el fitxer original i el fitxer traduït coincideixen en quantitat de nodes, jerarquia de tags HTML, etiquetes d'ancla (id) i objectius d'enllaços (href), sortint amb codi d'error 1 si detecta cap desajust.

uv run python /home/pquintana/.gemini/skills/epub-translator/scripts/verify_structure.py \

  --original-xhtml "<ruta_carpeta_temporal>/original_content.xhtml" \

  --translated-xhtml "<ruta_carpeta_temporal>/translated_content.xhtml"

Si es troben errors, cal corregir els corresponents fitxers revised_chunk_N.json i tornar a llançar el script de reconstrucció fins que la verificació surti correctament.

-​--

Adjunto tots els fitxers necessaris. No he comprovat que funcioni bé. Però deu estar 99% bé.