Automazione multilingue: il mio script AI-Powered Markdown Translator

Vedi progetto → GitHub

Sono felice di presentarvi il mio progetto AI-Powered Markdown Translator, uno script Python open source che traduce automaticamente i file Markdown del mio blog e alcuni README/documentazioni dei miei repository GitHub. Integrando modelli di intelligenza artificiale all’avanguardia come OpenAI, Mistral AI, Anthropic (Claude) e Google Gemini, questo strumento traduce articoli, README e documentazioni tecniche in 14 lingue, mantenendone struttura e formattazione. Questo progetto mette in luce le mie competenze in automazione, integrazione di IA e ingegneria dell’affidabilità, oltre alla mia passione per rendere i contenuti tecnici accessibili a tutti.

Non è solo uno script: è una prova della mia competenza e della mia visione per un mondo digitale più inclusivo.

Perché questo progetto?

I file Markdown sono essenziali per il mio ecosistema digitale: contengono i miei articoli del blog, tutorial e documentazioni open source. Automatizzandone la traduzione, rendo i miei contenuti accessibili a un pubblico globale. Il mio blog è ora disponibile in 14 lingue grazie a questo script — quasi 1.800 versioni tradotte (in termini approssimativi, escluse le fonti FR) sono oggi online su jls42.org, e il contatore cresce a ogni pubblicazione.

La v1.9 (maggio 2026) segna una svolta: codice sviluppato a sensazione (vibe coding) in pair-IA (Claude Code + Codex), protetto da uno stack di qualità industriale (14 hook, 229 test, SonarCloud, revisione PR assistita da IA) per puntare a un codice pulito anche quando ogni riga non viene riletta a mano.

Ecco alcuni esempi concreti dello script in azione:

Questo blog jls42.org in 14 lingue — l’intera esperienza editoriale multilingue (articoli, progetti, notizie sull’IA) è prodotta da questo script. Potete per esempio sfogliare la versione tedesca, giapponese, cinese, spagnola o araba del sito — ogni contenuto editoriale tradotto passa da lui (gli elementi dell’interfaccia, invece, provengono dal sistema i18n nativo di Astro).
Il README del progetto stesso è tradotto in 14 lingue su GitHub. Esempi: inglese, spagnolo, cinese.

Questo progetto mostra come l’IA possa risolvere problemi pratici favorendo al tempo stesso l’accessibilità.

Le mie competenze in primo piano

Questo progetto è una vetrina del mio know-how tecnico. Ecco cosa mette in evidenza:

Orchestrazione multi-modello: Claude Code in Opus per sviluppare, Codex come fallback, GPT-5.5 reasoning extra-high per mettere alla prova i piani, /pr-review-toolkit per la revisione prima del merge
Integrazione di più API di IA: 4 provider collegati (OpenAI, Mistral AI, Claude, Gemini), con adattamento alle specificità di ciascuna API (gestione di finish_reason / stop_reason, formati di risposta, limiti di token)
Ingegneria dell’affidabilità: convalida post-traduzione a doppio livello (deterministica anti-fuga verbatim + probabilistica langdetect), rilevamento dei silent failure, ritorni con stato esplicito
Stack di qualità industriale: 14 hook automatizzati (ruff, mypy, shellcheck, Opengrep SAST, pip-audit, Lizard…), 229 test unittest, 11 badge SonarCloud, più Codacy e CodeFactor
Spirito open source: disponibile su GitHub, GPLv3, README tradotto in 14 lingue

Questi aspetti testimoniano la mia capacità di creare strumenti potenti, affidabili e mantenibili nel lungo periodo.

Funzionalità principali

Ecco cosa offre lo script:

Multi-Provider: supporto a 4 API (OpenAI, Mistral AI, Claude, Gemini)
Modelli 2026: GPT-5.5, Claude Sonnet 4.6, Gemini 3.1 Pro di default
Modalità economica (--eco): modelli più veloci e meno costosi
File singolo (--file): tradurre un solo file invece di un intero directory
Conservazione del nome (--keep_filename): mantiene il nome e l’estensione originali (ideale per Astro, Hugo, ecc.)
Supporto .env: caricamento automatico delle chiavi API da un file .env
Supporto file .mdx: oltre ai classici file .md
Conservazione della formattazione: blocchi di codice, codice inline, link e metadati restano intatti

Novità v1.9 (maggio 2026):

Convalida post-traduzione: rilevamento automatico dei silent failure — lingua di destinazione verificata, troncamenti intercettati su tutti i provider.
Nota multi-posizione (--note_position, --note_format): in alto, in basso o entrambe; formato legacy o marker format compatibile con GitHub embed card.
Modalità --news rinforzata: già introdotta in v1.8 per proteggere le citazioni sorgenti EN tramite placeholder, in v1.9 beneficia di una convalida post-ripristino rafforzata (placeholder residuo = errore, citazione originale e URL di attribuzione verificati, flag di destinazione/sorgente controllati) — usata su tutti gli articoli ia-actualites del blog.

Provider	Qualità (predefinita)	Economica (`--eco`)
OpenAI	`gpt-5.5`	`gpt-5.4-mini`
Claude	`claude-sonnet-4-6`	`claude-haiku-4-5-20251001`
Mistral	`mistral-large-latest`	`mistral-small-latest`
Gemini	`gemini-3.1-pro-preview`	`gemini-3.1-flash-lite-preview`

Evoluzione v1.0 → v1.9

Versione	Data	Apporto principale
1.0–1.4	2024	OpenAI, poi Mistral, poi Claude
1.5	set. 2024	Refactor dei client, modelli 2024 (gpt-4o, claude-3.5-sonnet)
1.6	gen. 2026	Modelli 2026 (gpt-5, claude-sonnet-4-5, gemini-3-pro), Gemini, modalità `--eco`, file singolo (`--file`)
1.7	gen. 2026	`--keep_filename`, `.env`, codice inline preservato
1.8	mar. 2026	Modelli GPT-5.4 predefiniti, modalità `--news` con placeholder delle citazioni
1.9	mag. 2026	Convalida post-traduzione, nota multi-posizione, stack qualità 14 hook + 229 test + revisione IA

Sviluppo a sensazione + guardrail

Tutta la v1.9 è stata scritta in pair-IA. Il mio flusso: Claude Code (Opus, esclusivamente) scrive il codice, Codex prende il relais quando Opus si blocca o la finestra di utilizzo è satura, GPT-5.5 (reasoning extra-high) mette alla prova i piani prima dell’esecuzione, e lo skill /pr-review-toolkit:review-pr rilegge la PR prima di ogni merge. Io non rileggo il codice personalmente. Per rendere sostenibile in produzione questo modo di sviluppare, ho investito in uno stack di guardrail proporzionato:

14 hook automatizzati (pre-commit + pre-push): shellcheck, ruff, prettier, detect-secrets, Lizard CCN, mypy, Opengrep SAST, pip-audit, unittest
229 test unittest (~98 % di copertura sul nuovo codice v1.9)
Test pratici: multi-repo su README vari, uso interno del prodotto (dogfooding) sul blog (produzione = test live), verifica del rendering visivo (browser o anteprima Markdown)
3 piattaforme esterne: SonarCloud (11 badge), Codacy, CodeFactor
Skill /pr-review-toolkit:review-pr: revisione assistita da IA multi-agente prima del merge
Convalida post-traduzione a doppio livello: deterministica (anti-fuga verbatim) + probabilistica (langdetect)

L’idea non è dimostrare di saper fare ingegneria classica. È che non abbiamo scelta: codice IA non riletto merita più guardrail, non meno. Questa disciplina è descritta nel deep-dive tecnico.

In produzione su questo blog

Il progetto si traduce da solo: il suo README è in 14 lingue e genera tutte le versioni multilingue di questo blog.

Articoli del blog, 4 progetti e 98 articoli ia-actualites rappresentano quasi 1.800 versioni tradotte escluse le fonti FR (copertura per lingua variabile a seconda dei contenuti)
Modalità --news utilizzata sistematicamente sugli articoli ia-actualites per preservare le citazioni sorgenti EN
Guardrail v1.9 attivo da maggio 2026: dall’introduzione della doppia convalida post-traduzione, non ho più rilevato silent failure della lingua di destinazione
Meta-coerenza: la pagina che state leggendo in inglese, tedesco, giapponese… è tradotta da questo script

Per andare oltre

Per capire come è stata prodotta questa v1.9 (le novità nel dettaglio, il flusso di lavoro multi-modello, i guardrail messi in atto per puntare a un codice pulito senza rileggere), vedere il deep-dive tecnico completo.

E per confrontare il tono con una release precedente, l’articolo 2024 sulla v1.5 segue un formato di release notes più classico.

Provatelo voi stessi

Scoprite il progetto su GitHub, testatelo con i vostri file Markdown e condividete i vostri feedback. Le vostre idee mi aiutano a perfezionarlo!

Contatto : contact@jls42.org