Structural diff hook for translation quality — experience report & suggestion

[Alfystar]

Hi @DavidLMS 😁,

First of all, thank you for building Aphra. We've been using it in LibreFolio to automatically translate our MkDocs documentation (36 source files × 3 languages = 108 translated files), and the results have been genuinely impressive.

This issue isn't about a bug — it's about sharing what we built on top of Aphra and a suggestion that might benefit other users.

Our setup

We installed Aphra directly via Pipenv from your GitHub repository:

[dev-packages]
"aphra " = {git = "https://github.com/DavidLMS/aphra.git"}

This worked perfectly. You might consider mentioning Pipenv as an alternative installation method alongside pip/Poetry in your README — it's already supported out of the box since you have a proper setup.py/pyproject.toml.

What we customized

We wrapped Aphra's workflow (Analyze → Translate → Critique → Refine) inside an orchestration script (translate_docs.py) that adds:

1. Shared analysis — Step 1 (Analyze) runs once per source file and its result is reused across all 3 target languages. This saves ~25% of LLM calls.

2. Step 2 (Search) paused — We disabled the web search step entirely (APHRA_WEB_SEARCH=false). For technical documentation where terms are well-known, it added cost and latency without benefit.

3. Structural diff (our main addition) — Instead of relying solely on the LLM critic to catch structural issues, we created an objective, deterministic structural diff function (_structural_diff()) that compares the source and translated markdown on 13 dimensions:

   • Heading count and level sequence
   • Code block count and language tags
   • Link URLs (missing/added)
   • Image URLs
   • MkDocs admonition count (!!!, ???)
   • Horizontal rules, bullet lists, numbered lists
   • Table row count
   • Bold marker count
   • Line count delta

   The diff report is injected into the glossary parameter of the Critique step, so the critic LLM receives factual, objective data alongside its own subjective analysis. This dramatically reduced false negatives — issues the critic would have missed on its own.

4. Post-translation validation — A separate script (validate_translations.py) runs offline checks on all translated files (admonition indentation, artifact remnants like [N] glossary markers, truncated words, LaTeX corruption, etc.).

Suggestion: custom diff hook parameter

We think other Aphra users could benefit from a hook/callback parameter in the pipeline — something like:

def my_structural_diff(source: str, translated: str) -> str:
    """Return a factual report to inject into the critique step."""
    ...

aphra.translate(
    source_text,
    ...,
    structural_diff_fn=my_structural_diff,  # optional callback
)

This way, users could provide their own domain-specific quality checks (markdown structure for us, XML tags for others, JSON schema for i18n files, etc.) without forking the library.

Results

The Markdown structural diff is working well. We did have to clean up some "Translator's Notes" that the LLM occasionally appended, but overall the quality has been excellent — especially with cloud models (we used stepfun/step-3.5-flash via OpenRouter for the final run, $0 cost on their free tier).

We're also considering building a JSON i18n translation pipeline next (for our svelte-i18n frontend localization files), which would be a different beast but could reuse the same Aphra workflow with a JSON-aware structural diff.

Thank you

We wanted to share this experience not because there were problems, but in the hope that these ideas might help you improve the project. The Analyze → Critique → Refine architecture is really well thought out, and adding an objective diff layer on top of it made it even more powerful for our use case.

All our customization code is public in the LibreFolio repository — feel free to look at it, reuse it, or draw inspiration from it.

Keep up the great work! 🙏

[DavidLMS]

Hi @Alfystar 😊,

You can't imagine how happy this message makes me! Thank you so much for sharing how you're using Aphra — it's incredibly exciting to see it being useful in a project like LibreFolio.

Your use case is spectacular and there are so many ideas I'd love to incorporate. The Pipenv suggestion is a great one. And the shared analysis optimization to skip repeating Step 1 across languages is really clever — I think some kind of batch execution for multi-language translation would be a great addition to the core!

I built Aphra with the goal of making it easy to adapt to different use cases, so I love the approach you've taken. Would you mind if I added and linked your project as an example in the repository?

Aphra has several customization levels. For instance, you could avoid the translator's notes cleanup just by modifying the prompts — the current ones encourage that behavior because the only public workflow is designed for short blog articles. Your use case, technical documentation, would need a completely different workflow in my view.

Rather than adding a structural diff hook, I think the right move for Aphra's core is to implement a dedicated technical_docs workflow. I've been experimenting with subtitle translation, which has even more complex structural constraints (timing, IDs, reading speed), and the approach that works best is to prevent structural issues by design — extract the structure before translation, protect non-translatable elements, translate only the text, validate programmatically, and rebuild. That way the output structure is correct by construction, regardless of model quality. The problem with a hook feeding the critic is that the next LLM doesn't always "listen" to that feedback, and I want Aphra to guarantee structural correctness rather than hope for it.

That said, I think your approach is a great solution for your context and I totally understand it works well with the model choices you've made — both ideas are not mutually exclusive. Your structural diff work and the 13 dimensions you identified are incredibly valuable input for designing that workflow.

Thank you again for the feedback. You've contributed to Aphra's development more than you might realize 🙏

---

Ciao @Alfystar 😊,

Non immaginate quanto mi faccia felice questo messaggio! Grazie mille per aver condiviso come state usando Aphra — è davvero emozionante vederla utile in un progetto come LibreFolio.

Il vostro caso d'uso è spettacolare e ci sono tantissime idee che mi piacerebbe incorporare. Il suggerimento su Pipenv è ottimo. E l'ottimizzazione dell'analisi condivisa per evitare di ripetere lo Step 1 tra le lingue è davvero intelligente — credo che una sorta di esecuzione batch per la traduzione multilingue sarebbe un'ottima aggiunta al core!

Ho creato Aphra con l'idea che fosse facile adattarla a diversi casi d'uso, quindi mi piace moltissimo l'approccio che avete adottato. Vi dispiacerebbe se aggiungessi e linkassi il vostro progetto come esempio nel repository?

Aphra ha diversi livelli di personalizzazione. Per esempio, potreste evitare il cleanup delle note del traduttore semplicemente modificando i prompt — quelli attuali incoraggiano quel comportamento perché l'unico workflow pubblico è pensato per articoli brevi di blog. Il vostro caso d'uso, la documentazione tecnica, secondo me richiederebbe un workflow completamente diverso.

Piuttosto che aggiungere uno structural diff hook, credo che la mossa giusta per il core di Aphra sia implementare un workflow dedicato technical_docs. Ho sperimentato con la traduzione di sottotitoli, che ha vincoli strutturali ancora più complessi (timing, ID, velocità di lettura), e l'approccio che funziona meglio è prevenire i problemi strutturali by design — estrarre la struttura prima della traduzione, proteggere gli elementi non traducibili, tradurre solo il testo, validare programmaticamente e ricostruire. Così la struttura dell'output è corretta per costruzione, indipendentemente dalla qualità del modello. Il problema di un hook che alimenta il critico è che il LLM successivo non sempre "ascolta" quel feedback, e io voglio che Aphra garantisca la correttezza strutturale, non che la speri.

Detto ciò, penso che il vostro approccio sia un'ottima soluzione per il vostro contesto e capisco perfettamente che funzioni bene con le scelte di modello che avete fatto — le due idee non si escludono a vicenda. Il vostro lavoro sullo structural diff e le 13 dimensioni che avete identificato sono un contributo preziosissimo per progettare quel workflow.

Grazie ancora per il feedback. Avete contribuito allo sviluppo di Aphra più di quanto possiate immaginare 🙏

[Alfystar]

Ciao @DavidLMS scopro solo ora che siamo entrambi italiani, tanto vale parlaci semplice!

sono contento che ti siano piaciute le mie idee! Ammetto che ho trattato il tuo progetto un pò "blackBox" mi fossi messo ad analizzarlo meglio forse avrei evitato la parte del ripulire le note di traduzione 😜.
Credo che l'idea di creare un flusso dedicato per la documentazione sia ottima, anche perchè mi sto rendendo conto che tante piccolezze potrebbero perdersi, ad esempio la formattazione mkdown, un accapo di troppo o troppo poco può rompere di molto la renderizzazione.
Ho anche iniziato a pensare quindi ad un modo per "standardizzare" il testo che arriva all'LLM, sto vedendo che usare prettier non sembra essere tanto male, anche se bisogna stare un minimo attenti nella creazione del documento originale per essere rigorosi e avere un rendering indipendente, nulla di troppo complicato comunque.

Per ora sono passato a fare fasi più avanzate del progetto, ma appena le termino e ritorno ad aggiornare la documentazione, sperimento delle personalizzazioni nel workflow e poi magari ti faccio una PR!
Se nel frattempo rendi semplice, con un interfaccia standard, scegliere il workflow da usare, e per ogni step aggiungi la possibilità di iniettare ulteriore materiale personalizzato, appena ritorno e aggiorno il repo, ho modo di fare le mie prove senza stravolgerti il progetto!
Per usarlo preferirei, e credo sarebbe anche meglio per altri, avere la possibilità di sovrascrivere da interfaccia standard (dopo averlo installato con pip o pipenv) il prompt che si andrà ad usare, altrimenti bisogna sempre colonare/forkare, basterebbe poter inviare una stringa con il prompt o passare il path del file con il prompt, probabilmente la stringa è già sufficiente, se uno volesse farsi un file se lo crea, se lo apre e legge e poi passa il contenuto.
in mancanza del parametro usi il promt di default per quel workflow.
Se ti servono altre idee, sono un pozzo in piena 😜🤣

Riguardo al linkare il nostro repo, con estremo piacere!!! Io vi ho già messo nei crediti della pagina doc, in tutte e 4 le lingue 😝!
Al termine del progetto core, poverò a espandere in automatico almeno a cinese, coreano e giapponese, sia la doc che il json con le traduzioni delle interfacce i18n, e lì si che ce ne saranno delle belle, quando ci arrivo, se vuoi cooperare con me, mi farebbe taaaantisimo piacere

[DavidLMS]

Ciao di nuovo @Alfystar 😊! A dire il vero non sono italiano 😅. Però lo capisco quando lo leggo e mi è sembrata una buona idea sfruttare gli strumenti che abbiamo per favorire uno scambio di idee più rilassato. Grazie mille per aver menzionato il progetto nei vostri crediti!

Mi sembra una buona idea quella di usare qualcosa come Prettier, anche se io stavo pensando a qualcosa di più tipo AST. Mi piacerebbe che per usare 🌐💬 Aphra non si debba adattare il documento, ma che sia il flusso ad adattarsi ad esso. Anche che tutto ciò che può essere risolto programmaticamente venga utilizzato per controllare l'output degli LLM e che la traduzione sia affidabile, anche se questo comporta un maggiore consumo di token. Tuttavia, ci sono molte soluzioni possibili e sono tutte benvenute. Possono persino esistere flussi diversi per compiti simili e che gli utenti possano scegliere quelli che si adattano meglio al loro caso d'uso o budget 😁.

A dire il vero non avevo mai pensato a 🌐💬 Aphra come dipendenza, piuttosto che ognuno potesse incorporarla direttamente nel proprio progetto. Però mi hai dato tante idee e ho pensato che non fosse male dare questa possibilità all'utente. Quindi ho inserito in una nuova release quello che chiedevi: la possibilità di scegliere il workflow e di personalizzare i prompt senza toccare il codice originale (ora puoi sostituire un prompt completamente o aggiungere qualcosa all'inizio o alla fine di qualsiasi prompt). Spero che soddisfi le vostre aspettative. In ogni caso è retrocompatibile. Ho anche aggiunto nella documentazione le istruzioni per usare pipenv e una nuova sezione per mettere in evidenza i progetti che usano 🌐💬 Aphra. Il vostro è il primo di cui sono a conoscenza! 🥇

Un grande in bocca al lupo con il vostro progetto e, naturalmente, se andate avanti con altri tipi di traduzioni ed esigenze come quella dell'i18n, sono felicissimo di collaborare. Per lavoro di solito sono più libero a partire da maggio, ma per piccole cose posso sempre ritagliarmi un momento. Continuiamo ad andare avanti! 🤞

[Alfystar]

Hi @DavidLMS 😊,

I'm back with an update! We just completed a full documentation translation run with the new pipeline — and it went great. Here's what happened and what we built since last time.

The full run

We scaled from 36 source files to 90 source files × 3 languages = 270 translated documents. The docs now cover user guides, admin manuals, financial theory (with heavy LaTeX), gallery pages, and more — everything except the Developer Manual which stays EN-only.

We used google/gemma-4-31b (via OpenRouter, free tier) for the bulk translation, and I have to say it was surprisingly good at handling Markdown + LaTeX + MkDocs admonitions. Very few structural errors, and the translation quality was excellent across IT/FR/ES. For the structural diff + critique pass we used a larger model, which made it easy to catch and auto-fix the few issues that slipped through.

New features we built on top of Aphra

Since our last conversation, we added quite a few things to our orchestration layer. All functional ideas — feel free to take inspiration from any of them:

1. Parallel multi-language translation (--workers N) — Each source file's analysis is shared, then languages are translated concurrently using a thread pool. With --workers 20, the full 201-task run completed much faster. Thread-safe logging keeps output readable.

2. Smart caching with MD5 hashes — Source file MD5 + per-language completion status stored in .translate-hashes.json. Unchanged files are automatically skipped on re-runs. This made iterative runs (fixing failures, adding new files) very efficient.

3. Per-line structural diff detail — The diff report now shows which specific line has the mismatch, with both EN and translated text side by side. For example:

   BOLD_MARKERS: source=24, translated=23 (Δ-1)
     L39: src=2 trn=1
       EN: ...define a penalty rate... **grace period**
       TR: ...définir un taux de pénalité... Un délai de grâce
   

   This made it trivial to locate and fix issues.

4. 10-step automatic post-translation cleanup (_clean_translation()):

   • Strips <translation> tags, translator's notes (6+ multilingual variants), glossary blocks, footnotes
   • Normalizes internal .XX.md links back to .md (MkDocs i18n requirement)
   • Auto-fixes admonition indentation (LLMs consistently produce 1-space indent instead of the 4 spaces MkDocs Material requires — we caught 632 lines across 131 files!)
   • Collapses excessive blank lines, normalizes double spaces

5. --issues-only flag for the diff CLI — Essential when checking 270 files: shows only warnings, hides the 264 clean results.

6. Prompt override integration — We used your new prompt override feature (thank you for implementing it!) to customize the workflow for our technical documentation context. The prompts reference LibreFolio specifically, but a more generic version could be a solid starting point for any MkDocs-based Python project — there are various compilation constraints (admonitions, LaTeX blocks, Mermaid diagrams, attr_list anchors) that need to be preserved.

About the code

I want to be upfront: since this isn't the core part of our project, I was happy with the AI-generated code. It works well but I'll admit it's not optimally structured — however, the ideas are all there and it served us perfectly. Everything is public in the main branch of the LibreFolio repository under mkdocs_src/aphra-pipeline/ if you want to look at it.

What's next for us

We're now moving on to the next phase of the app (currency conversion, chart improvements, mobile UX). When we circle back to update the documentation, we'll likely add more source files and possibly expand to Chinese/Japanese/Korean — that's when we'll really stress-test the pipeline!

Thank you

Thank you again for Aphra and for your responsiveness. The prompt override feature you added was exactly what we needed. And thank you for listing LibreFolio as an example project — that means a lot to us! 🙏

Keep up the amazing work, and let's stay in touch for when the i18n JSON translation phase comes around! 🤞