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.