Django i18n: La Guida Completa all'Automazione della Traduzione dei File .po

Se hai mai distribuito un'app Django in più di una lingua, conosci la procedura. Racchiudi le tue stringhe in gettext(), esegui makemessages, apri un file .po con centinaia di voci e inizi a tradurre riga per riga. Per due lingue e cinquanta stringhe, è tollerabile. Per sei lingue e cinquecento stringhe, è un'intera giornata lavorativa che non riavrai mai indietro.

Questa guida copre la pipeline di internazionalizzazione (i18n) di Django dall'inizio alla fine, spiega dove si inceppa e mostra come automatizzare la parte più faticosa con la traduzione basata sull'intelligenza artificiale.

Il Workflow Standard di Django i18n

Il sistema i18n integrato di Django è ben progettato. Il ciclo principale è questo:

Passo 1: Contrassegna le stringhe per la traduzione nel tuo codice Python e nei template:

from django.utils.translation import gettext as _

def dashboard(request):
    welcome = _("Welcome back, %(name)s!") % {"name": request.user.first_name}
    return render(request, "dashboard.html", {"welcome": welcome})

{% load i18n %}
<h1>{% trans "Account Settings" %}</h1>
<p>{% blocktrans %}You have {{ count }} unread messages.{% endblocktrans %}</p>

Passo 2: Estrai le stringhe nei file .po:

python manage.py makemessages -l de -l fr -l nl

Questo scansiona l'intero codice sorgente e genera un file .po per lingua, contenente ogni stringa traducibile:

#: myapp/views.py:4
msgid "Welcome back, %(name)s!"
msgstr ""

#: templates/dashboard.html:2
msgid "Account Settings"
msgstr ""

Passo 3: Traduci ogni msgstr vuoto a mano.

Passo 4: Compila i file .po completati in file binari .mo:

python manage.py compilemessages

I passi 1, 2 e 4 sono veloci. Il passo 3 è dove il processo si blocca.

Perché la Traduzione Manuale Non Scala

Un'applicazione Django tipica ha tra le 200 e le 2.000 stringhe traducibili. Moltiplica questo per il numero di lingue target e ti ritrovi con un impegno di tempo considerevole.

Questa non è una lamentela teorica. In un noto thread del Django Forum, uno sviluppatore ha riportato di aver speso oltre 8 ore per file .po facendo traduzioni manuali. Un contributore core di Django ha descritto di aver speso oltre 10 ore per incorporare le traduzioni inviate dalla community in un singolo rilascio, principalmente per revisione, correzioni di formattazione e correzione di placeholder rotti.

I problemi si accumulano nel tempo:

• I placeholder si rompono. Copia una stringa come Welcome, %(name)s! in Google Translate e spesso otterrai Willkommen, %(Name)s! o Bienvenue, %(nom)s!. Quella sottile corruzione causa crash a runtime.
• La coerenza si perde. Senza un glossario, "dashboard" viene tradotto come "Instrumententafel" in un file e "Dashboard" in un altro. Tre mesi dopo, nessuno ricorda quale fosse intenzionale.
• Gli sprint aggiungono stringhe. Ogni feature branch aggiunge nuove stringhe traducibili. Anche se hai pagato per un passaggio di traduzione completo lo scorso trimestre, ora hai 40 voci non tradotte sparse nei tuoi file .po.
• Gli assistenti AI aiutano una volta. Puoi incollare un file .po in ChatGPT o Claude e ottenere risultati decenti. Ma allo sprint successivo, quando compaiono 15 nuove stringhe, stai facendo prompt da zero, ritradugendo l'intero file e sperando che rimanga coerente con quello che c'era già.

La causa principale è che la traduzione viene trattata come un evento una tantum invece di un processo incrementale e ripetibile.

Automatizzare la Traduzione con l'AI

L'idea è semplice: invece di un umano che apre ogni file .po e compila i valori msgstr, uno strumento legge il file, invia le stringhe non tradotte a un modello AI o API di traduzione, scrive i risultati e preserva tutto il resto (commenti, struttura del file, placeholder, forme plurali).

TranslateBot Django è un pacchetto open-source che fa esattamente questo. Si integra nel sistema di management command di Django, quindi si inserisce nel workflow che hai già.

Configurazione Passo per Passo

1. Installa il Pacchetto

pip install translatebot-django

Oppure, se usi uv (consigliato):

uv add --dev translatebot-django

Installarlo come dipendenza di sviluppo è intenzionale. Hai bisogno di TranslateBot solo quando generi le traduzioni, non a runtime in produzione.

2. Aggiungi a INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # ...
    "translatebot_django",
]

3. Configura il Tuo Provider AI

# settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"

TranslateBot usa LiteLLM sotto il cofano, il che significa che puoi sostituire qualsiasi dei 100+ modelli cambiando una singola stringa:

Per DeepL, installa l'extra: pip install translatebot-django[deepl]. Il piano gratuito di DeepL ti offre 500.000 caratteri al mese senza costi, sufficienti per la maggior parte dei progetti di piccole e medie dimensioni.

4. Definisci le Tue Lingue

# settings.py
LANGUAGES = [
    ("en", "English"),
    ("de", "German"),
    ("fr", "French"),
    ("nl", "Dutch"),
    ("ja", "Japanese"),
]

5. Esegui la Traduzione

python manage.py translate

Questo è tutto. TranslateBot scansiona il tuo progetto alla ricerca di file .po, identifica le voci non tradotte, le invia al modello AI configurato in batch ottimizzati e scrive i risultati. Le traduzioni esistenti non vengono toccate.

Per tradurre una singola lingua:

python manage.py translate --target-lang nl

L'output appare così:

Translating to Dutch (nl)...
Found 42 strings to translate
Translating batch 1/2...
Translating batch 2/2...
Successfully translated 42 strings

6. Compila Come al Solito

python manage.py compilemessages

Il tuo workflow completo ora è:

python manage.py makemessages -l de -l fr -l nl -l ja
python manage.py translate
python manage.py compilemessages

Tre comandi. Ogni lingua. Ogni sprint.

Incrementale per Design

La caratteristica più importante per un workflow ripetibile è la traduzione incrementale. TranslateBot traduce solo le voci dove msgstr è vuoto. Se hai 500 stringhe e 15 sono nuove in questo sprint, solo quelle 15 vengono inviate all'API.

Questo è importante per ragioni pratiche:

1. Costo. Paghi solo per le nuove stringhe, non per l'intero file.
2. Velocità. Tradurre 15 stringhe richiede secondi, non minuti.
3. Stabilità. Le traduzioni che hai già revisionato e approvato non vengono mai sovrascritte (a meno che non passi esplicitamente --overwrite).

Sicurezza dei Placeholder

Django utilizza diversi formati di placeholder: %(name)s, %s, %d, {0}, {name} e tag HTML inline come <strong> o <a href="...">. Se qualcuno di questi viene alterato nella traduzione, ottieni errori a runtime o markup rotto.

TranslateBot istruisce il modello AI a preservare tutti i formati di placeholder e valida l'output. Una stringa come:

Welcome to %(site_name)s! You have <strong>%(count)d</strong> new messages.

Viene tradotta in olandese come:

Welkom bij %(site_name)s! Je hebt <strong>%(count)d</strong> nieuwe berichten.

Ogni placeholder sopravvive intatto.

Controllare la Qualità con TRANSLATING.md

I modelli AI traducono meglio quando comprendono il contesto. TranslateBot cerca un file TRANSLATING.md nella root del tuo progetto e include il suo contenuto in ogni richiesta di traduzione.

# Translation Context

## About This Project
A B2B project management tool for construction companies.

## Terminology
- "project" means a construction project, not a software project
- "plan" means a building plan/blueprint, not a subscription plan
- Keep "Gantt chart" as-is in all languages

## Tone
- German: use formal "Sie" form (business context)
- French: use formal "vous" form
- Dutch: use informal "je" form

## Do Not Translate
- Brand name: "BuildFlow"
- Feature names: "SmartSchedule", "CostTracker"

Questo file è versionato insieme al tuo codice, così tutto il team condivide lo stesso contesto di traduzione. Puoi anche posizionare file TRANSLATING.md per singola app per le app con terminologia specializzata. Un modulo di cartelle cliniche e un modulo di fatturazione possono avere ciascuno il proprio glossario.

Anteprima Prima del Commit

Il flag --dry-run mostra esattamente cosa verrebbe tradotto senza effettuare chiamate API o modificare file:

python manage.py translate --target-lang fr --dry-run

Found 15 untranslated entries
Dry run mode: skipping LLM translation

Would translate 'Welcome to our site'
Would translate 'Hello, %(name)s!'
...

Dry run complete: 15 entries would be translated

Questo è utile prima di un grande ciclo di traduzione o quando si introduce un nuovo membro del team che vuole capire cosa fa il comando prima di impegnarsi con i costi dell'API.

Integrazione CI/CD

Le traduzioni che diventano obsolete sono inevitabili senza un'applicazione rigida. TranslateBot include un management command check_translations progettato per le pipeline CI:

# .github/workflows/ci.yml
jobs:
  translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          enable-cache: true
      - run: uv python install
      - run: uv sync --frozen
      - name: Install gettext
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends gettext
      - name: Check translations
        run: uv run python manage.py check_translations --makemessages

Il flag --makemessages esegue makemessages -a --no-obsolete prima, assicurando che i file .po riflettano il codice sorgente attuale prima del controllo. Se qualche voce è non tradotta o fuzzy, il comando esce con codice 1 e fa fallire la build:

locale/de/LC_MESSAGES/django.po: 2 untranslated, 0 fuzzy
locale/nl/LC_MESSAGES/django.po: 0 untranslated, 1 fuzzy
CommandError: Translation check failed

Il workflow tipico dello sviluppatore diventa:

1. Aggiungere nuove stringhe traducibili in un feature branch.
2. La CI fallisce perché quelle stringhe non sono tradotte.
3. Eseguire python manage.py translate localmente.
4. Committare i file .po aggiornati.
5. La CI passa.

Le traduzioni non si desincronizzano mai silenziosamente.

Tradurre il Contenuto del Database

Se la tua applicazione memorizza contenuto traducibile nel database (nomi di prodotti, titoli di post del blog, etichette di categorie), TranslateBot si integra anche con django-modeltranslation:

pip install translatebot-django[modeltranslation]

# Translate all registered model fields
python manage.py translate --target-lang de --models

# Translate specific models only
python manage.py translate --target-lang de --models Product Category

La stessa logica incrementale si applica: solo i campi dove il valore della lingua target è vuoto vengono tradotti.

Confronto dei Costi

Una delle domande più frequenti è se la traduzione AI sia conveniente rispetto alle alternative. Ecco un confronto approssimativo per un progetto con 500 stringhe traducibili in 5 lingue:

I numeri cambiano in base al numero di stringhe e alle lingue target, ma la differenza di ordine di grandezza è costante. Per la manutenzione continuativa (tradurre le 20-50 nuove stringhe aggiunte ogni sprint), il costo dell'AI è essenzialmente zero.

Migliori Pratiche

Inizia con --dry-run. Prima del tuo primo vero ciclo di traduzione, visualizza in anteprima cosa accadrà. Questo costruisce fiducia e rileva problemi di configurazione in anticipo.

Committa i file .po prima di tradurre. Se qualcosa va storto, git checkout ti riporta a uno stato pulito istantaneamente.

Scrivi un TRANSLATING.md dal primo giorno. Anche un breve file con la descrizione del tuo progetto e alcune regole terminologiche migliora misurabilmente la qualità della traduzione.

Aggiungi check_translations alla CI. Questo singolo passo previene la modalità di fallimento i18n più comune: stringhe che sono state contrassegnate per la traduzione ma mai effettivamente tradotte.

Usa gpt-4o-mini o DeepL per l'efficienza dei costi. Riserva i modelli premium come GPT-4o o Claude per i progetti dove la precisione conta, come testi di marketing, testi legali o terminologia specifica del dominio.

Revisiona le stringhe critiche. Le traduzioni AI sono sufficientemente buone per la maggior parte del testo dell'interfaccia, ma fai revisionare a un madrelingua qualsiasi testo legalmente vincolante, critico per la sicurezza o rivolto al cliente in un contesto ad alto rischio.

Da Ore a Secondi

Il framework i18n di Django è eccellente nell'estrarre e compilare le traduzioni. Il divario è sempre stato il passo della traduzione in sé, il lavoro tedioso e soggetto a errori di compilare centinaia di valori msgstr in più lingue.

TranslateBot colma quel divario. Installalo, puntalo a un provider AI ed esegui un comando. Le nuove stringhe vengono tradotte. Le stringhe esistenti restano intatte. I placeholder rimangono intatti. La CI cattura tutto quello che sfugge.

I tuoi file .po smettono di essere un compito ingrato e diventano semplicemente un'altra parte della build.

pip install translatebot-django

Inizia su translatebot.dev.