Open Source6 min

Italian Profanity: una libreria open source per riconoscere parolacce e bestemmie italiane

Ho sviluppato Italian Profanity per filtrare nickname e testi brevi in JavaScript, TypeScript e Flutter: regole italiane, varianti Unicode, attenzione ai falsi positivi e stessi esiti tra web e mobile.

Elia Zavatta
Italian Profanity: una libreria open source per riconoscere parolacce e bestemmie italiane

Quando sviluppi un'app con nickname, nomi di stanze o team, prima o poi qualcuno prova a usare parole offensive. Il problema non è solo riconoscere le parolacce più evidenti: ci sono lettere sostituite con numeri, spazi aggiunti apposta, accenti, caratteri Unicode simili e bestemmie scritte in molti modi. Allo stesso tempo, un filtro troppo aggressivo rischia di bloccare nomi perfettamente innocui.

Per questo ho creato Italian Profanity: una libreria open source con un motore JavaScript/TypeScript e uno Dart/Flutter. È pensata soprattutto per testi brevi in italiano, lavora offline, non richiede dipendenze a runtime ed è distribuita con licenza MIT. Non è un servizio di moderazione in cloud: il controllo avviene nell'applicazione che la integra.

Perché un filtro italiano richiede regole proprie

Molti filtri generici sono costruiti intorno all'inglese o intorno a liste di parole senza contesto. In italiano serve maggiore attenzione a flessioni, composti, termini colloquiali e soprattutto bestemmie. Inoltre non basta cercare una sottostringa: una corrispondenza casuale dentro un nome può essere un falso positivo.

Italian Profanity distingue tra rilevamento e decisione. Il motore identifica i possibili match; la policy decide se consentire, chiedere una revisione o bloccare. Il termine «dio», da solo, non viene trattato automaticamente come bestemmia: il controllo cerca combinazioni specifiche. I nomi e i cognomi ambigui richiedono invece prudenza, non blocchi indiscriminati.

Quali varianti riconosce

  • Leetspeak: sostituzioni come «D10 p0rc0» al posto di lettere normali.
  • Lettere separate, ripetute o accentate, anche quando l'obiettivo è aggirare il filtro.
  • Caratteri Unicode visivamente simili, comprese alcune lettere cerchiate e forme matematiche.
  • Nickname composti con trattini, punti, underscore, cifre esterne e CamelCase.
  • Combinazioni di bestemmie e termini offensivi, senza considerare automaticamente offensiva ogni parola che contiene una sequenza di lettere sospetta.

Il dataset comprende 290 regole italiane curate e 1.034 forme dichiarate, più frasi e combinazioni. È disponibile anche un lessico inglese opzionale, che va attivato esplicitamente. Non considero però questi numeri una garanzia di copertura completa: dialetti, nuovi modi di scrivere e contesti particolari restano casi aperti.

Esempi: bloccare l'elusione, non i nomi innocui

Esempi dimostrativi con configurazione predefinita; l'esito può dipendere da profilo, opzioni e versione.
Testo di esempioEsito attesoMotivo
D10 p0rc0blockCombinazione offensiva scritta in leetspeak
ClaudioallowNome proprio, non un insulto
DiodatoallowNome proprio, non una bestemmia
ⒸⓐⓩⓩⓞblockCaratteri Unicode normalizzabili

Come si integra in JavaScript e Flutter

Per JavaScript o TypeScript basta installare il pacchetto da npm con il comando «npm install italian-profanity». Per Dart e Flutter il pacchetto equivalente si chiama italian_profanity: puoi aggiungerlo con «dart pub add italian_profanity» oppure «flutter pub add italian_profanity».

Le API principali sono findMatches(), check(), isClean() e createChecker(). check() restituisce una decisione di tipo allow, review o block; findMatches() permette di leggere i rilevamenti in modo separato. Puoi scegliere i profili balanced, strict e lenient, aggiungere eccezioni e regole personalizzate o attivare il riconoscimento dei contatti. La guida di integrazione contiene gli esempi completi per entrambe le piattaforme.

Due motori, ma le stesse decisioni

Uno degli obiettivi tecnici era evitare che il server JavaScript e l'app Flutter dessero risposte diverse sullo stesso nickname. Le regole e le aspettative dei test sono quindi condivise tra i due motori. Il progetto include migliaia di fixture di regressione e un audit su 127.842 input per ciascuna delle configurazioni linguistiche principali, con attenzione specifica alle collisioni su nomi, cognomi e parole comuni.

Ogni aggiornamento può rendere il filtro più severo su alcune scritture: per questo il repository pubblica un changelog e confronti di comportamento fra release. Se validi i testi sia nel client sia sul server, conviene allineare versioni e configurazioni e trattare esplicitamente l'esito review.

Limiti e prossimi passi

Il filtro è stato costruito e verificato tecnicamente, ma la validazione su testi di utenti reali è un lavoro diverso. Le priorità sono raccogliere esempi di falsi positivi e di elusioni sfuggite al controllo, ampliare il lessico solo quando i nuovi casi sono motivati e verificare che ogni aggiunta non rompa ciò che funziona già. Non memorizzerei i testi degli utenti per fare analytics senza un motivo preciso e tutele adeguate.

La libreria resterà gratuita e open source. Chiunque può usarla nei propri prodotti, proporre miglioramenti o aprire una segnalazione su GitHub. Per integrazioni più complesse e sistemi di moderazione su misura, il progetto è anche un esempio concreto del tipo di software che sviluppo.

Il codice, i test, le istruzioni per Dart/Flutter e la documentazione sono nel repository GitHub. Se vuoi contribuire, parti dalle issue e dalla guida per i contributori: i casi reali e riproducibili sono più utili di liste di parole aggiunte senza verifiche.

Tecnologie

TypeScriptJavaScriptDartFlutterOpen Source

Se questo problema ti riguarda

Continua a leggere

Hai un progetto?

Parliamone

Mandami due righe su cosa devi costruire o migliorare. Ti rispondo con domande concrete, non con una proposta generica.

Non sai ancora quale budget serve? Fai una prima stima.

I dati servono solo per rispondere alla richiesta. Dettagli nella privacy policy.