Il 15 gennaio 2026 Google ha lanciato TranslateGemma, una famiglia di modelli di traduzione aperti basata su Gemma 3, disponibile in tre dimensioni – 4 B, 12 B e 27 B parametri – e capace di gestire 55 lingue. I pesi sono scaricabili da Kaggle e Hugging Face e, a differenza delle API cloud, possono essere eseguiti localmente senza inviare dati sensibili a server esterni.
Perché scegliere un traduttore AI offline?
Le aziende italiane ed europee hanno spesso l’obbligo di proteggere dati personali, segreti commerciali o documenti legali. Inviare questi testi a un provider terzo richiede una valutazione normativa e contrattuale complessa. Un traduttore AI installato in locale elimina il rischio di fuga di informazioni: il testo rimane nella macchina dell’utente e non attraversa la rete.
Oltre alla sicurezza, l’installazione locale permette di misurare autonomamente le prestazioni del modello sul proprio hardware e sui propri documenti. Con gli script di valutazione inclusi (chrF, BLEU e COMET) è possibile confrontare rapidamente diverse configurazioni e scegliere la più adatta al caso d’uso.
Requisiti di sistema e versioni consigliate
Il progetto è compatibile con Linux, macOS e Windows (tramite WSL2). È necessario disporre di una GPU per velocizzare l’inferenza, ma non è obbligatoria: il modello 4 B può essere eseguito anche su CPU, accettando tempi più lunghi. Prima di scaricare il modello, verifica la dimensione del file GGUF per assicurarti di avere sufficiente RAM e spazio di swap.
Le versioni dei componenti sono cruciali perché llama.cpp ha subito importanti cambiamenti a novembre 2026. La release v1.0.0 (13 nov 2026) introduce un’API C stabile, rimuove 35 funzioni deprecate e rafforza llama-server contro SSRF, CORS impropri e DNS rebinding. Per questo motivo la tabella qui sotto parte dal tag v1.0.0:
- Python: 3.12 (minimo 3.10); vLLM richiede 3.10+
- llama.cpp: tag v1.0.0 (esistono build settimanali come b12566 del 20 nov)
- Modello: TranslateGemma 4B o 12B in GGUF; 27B solo con molta memoria
- Libreria client: openai (ultima versione) – usa l’endpoint
/v1/chat/completions - Valutazione: sacrebleu e unbabel‑comet (COMET opzionale, richiede modello separato)
- vLLM (facoltativo): 0.34.0, richiede CUDA 13.x per multi‑utente
- CUDA toolkit: 13.x, solo se compili con supporto GPU Nvidia
Gli strumenti da riga di comando richiesti sono git, cmake e un compilatore C++. In alternativa è possibile scaricare i binari precompilati di llama.cpp per evitare la compilazione.
Scegliere la taglia giusta del modello
TranslateGemma non è un prodotto a pagamento né un’API a consumo; è una collezione di pesi open‑source. La scelta della taglia dipende dal contesto hardware e dal livello di qualità richiesto:
- 4 B: ideale per dispositivi edge, laptop senza GPU o traduzioni interattive di frasi brevi.
- 12 B: il miglior compromesso per workstation portatili o desktop con GPU di medio livello; consigliato per la maggior parte dei documenti di lavoro.
- 27 B: riservato a workstation con GPU di fascia alta (es. Nvidia H100) o TPU; garantisce la massima qualità, specialmente per lingue rare o testi complessi.
È importante notare che i file GGUF pubblicati dalla community (es. repository Menterium o mydubber‑org) sono conversioni quantizzate dei pesi originali e non rilasci ufficiali di Google. Prima di usarli in produzione, controlla sempre la licenza di Gemma e le note del repository, poiché alcuni build perdono funzionalità (ad esempio la gestione delle immagini) o riportano metriche non verificate.
Passi 1‑2: preparazione dell’ambiente Python e struttura del progetto
Creare un virtualenv isolato evita conflitti di dipendenze. Esegui i seguenti comandi (bash/zsh; su Windows usa .venv\Scripts\activate):
mkdir traduttore-locale
cd traduttore-locale
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
requirements.txt
openai
huggingface_hub
sacrebleu
pytest
fastapi
uvicorn
pip install -r requirements.txt
La struttura consigliata è:
traduttore-locale/
requirements.txt
scarica_modello.py
data/
glossario.json
testenit.jsonl
esempio.md
models/
src/traduttore/
_init_.py
config.py
client.py
prompt.py
chunker.py
glossario.py
cache.py
cli.py
valuta.py
confronta.py
api.py
tests/
test_chunker.py
test_glossario.py
Il file config.py gestisce tutte le impostazioni tramite variabili d’ambiente, permettendo di passare facilmente da un server locale a uno remoto o a una porta diversa.
Esempio di config.py
# src/traduttore/config.py
import os
from dataclasses import dataclass
@dataclass
class Config:
host: str = os.getenv('TRADUTTORE_HOST', '127.0.0.1')
port: int = int(os.getenv('TRADUTTORE_PORT', '8080'))
modelpath: str = os.getenv('TRADUTTOREMODEL', 'models/translategemma-12b.gguf')
cachedb: str = os.getenv('TRADUTTORECACHE', '.cache/cache.sqlite')
apikey: str = os.getenv('TRADUTTOREAPI_KEY', '')
Passi 3‑5: compilazione di llama.cpp e avvio del server
Clona il repository llama.cpp, passa al tag v1.0.0 e compila con supporto CUDA se disponibile:
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
git checkout tags/v1.0.0
mkdir build && cd build
cmake .. -DLLAMACUDA=ON -DCMAKEBUILD_TYPE=Release
make -j$(nproc)
Scarica il modello GGUF desiderato e posizionalo nella cartella models/. Avvia il server con:
./bin/llama-server -m ../models/translategemma-12b.gguf -c 4096 --port 8080
Il server espone un endpoint compatibile con l’API OpenAI, quindi il client Python può interagire usando la libreria openai:
import openai
client = openai.OpenAI(base_url='http://127.0.0.1:8080/v1')
response = client.chat.completions.create(
model='translategemma',
messages=[{'role': 'user', 'content': 'Traduci questo testo in italiano.'}]
)
print(response.choices[0].message.content)
Passi 6‑8: chunking, glossario e cache SQLite
Per tradurre documenti lunghi senza rompere markup Markdown o blocchi di codice, il modulo chunker.py divide il testo in sezioni logiche mantenendo gli stili. Un esempio di algoritmo:
def chunktext(text, maxtokens=1024):
# 1. Split per blocchi di codice (```…```) e markdown headings
# 2. Accumula token count finché non supera max_tokens
# 3. Restituisce lista di chunk
Il glossario, definito in glossario.json, elenca termini da non tradurre (es. nomi di prodotto, sigle). Durante la generazione, il prompt include una sezione “Non tradurre” con questi termini, riducendo errori di sostituzione.
La cache utilizza SQLite (cache.py) per memorizzare traduzioni già effettuate, evitando richieste duplicate. La chiave è il hash del chunk più il modello usato; il valore è il testo tradotto e i metadati (tempo, token usati).
Passi 9‑10: script di valutazione automatico
Per confrontare le traduzioni generate con un riferimento, il progetto fornisce valuta.py, che calcola:
- chrF: misura di similarità basata su character n‑gram.
- BLEU: tradizionale metric di precisione.
- COMET (opzionale): modello di apprendimento profondo che valuta fedeltà semantica.
Esempio di utilizzo:
python -m src.traduttore.valuta \
--reference data/testenit.jsonl \
--hypothesis data/traduzioni_output.txt \
--metrics chrf bleu comet
COMET richiede l’installazione di PyTorch e il download di un modello pre‑addestrato; il setup è gestito da requirements.txt opzionale.
Passi 11‑12: test, benchmarking e distribuzione
Il modulo tests/ contiene unit test per il chunker e il glossario. Esegui con pytest -q per verificare l’integrità del codice. Per il benchmark hardware, registra il tempo medio di risposta e il consumo di VRAM con nvidia‑smi (se disponibile) o time su CPU.
Infine, per offrire l’interfaccia REST al resto dell’azienda, il file api.py espone endpoint FastAPI che incapsulano le chiamate al server llama‑server. Avvia con:
uvicorn src.traduttore.api:app --host 0.0.0.0 --port 8000
Gli utenti interni possono così inviare richieste POST con il testo da tradurre, ricevendo la risposta in JSON. La combinazione di FastAPI + SQLite cache garantisce scalabilità leggera senza dipendere da servizi esterni.
Conclusioni
Grazie a TranslateGemma e llama.cpp, è possibile costruire un traduttore AI completamente offline in circa 85 minuti, seguendo i 12 passi descritti. La soluzione offre:
- Zero trasferimento di dati fuori dalla rete aziendale.
- Controllo totale su hardware, versioni e licenze.
- Possibilità di valutare e ottimizzare le prestazioni con metriche standard.
- Scalabilità modulare tramite FastAPI e cache SQLite.
Con un investimento minimo in tempo e risorse, le imprese possono garantire la riservatezza dei propri contenuti e mantenere un alto livello di qualità nella traduzione automatica, sfruttando l’ultima generazione di modelli open‑source di Google.
