Cum să traduci conținutul bazei de date Django cu AI

Daca ai lucrat cu framework-ul de internationalizare (i18n) integrat in Django, stii ca gestioneaza bine string-urile statice. Impachetarea textului in gettext() sau folosirea tag-ului de template {% trans %} extrage string-urile in fisiere .po, pe care traducatorii le completeaza. Sistemul este testat in lupta si functioneaza excelent pentru cod si template-uri.

Dar ce faci cu continutul stocat in baza ta de date?

Nume de produse, titluri de articole, descrieri de categorii, raspunsuri la FAQ, continut generat de utilizatori. Nimic din toate acestea nu se afla in codul tau sursa. Comanda makemessages din Django nu le va gasi niciodata, iar fisierele .po nu te pot ajuta aici. Daca aplicatia ta serveste continut dinamic utilizatorilor in mai multe limbi, ai nevoie de o strategie diferita.

Iata cum se face: foloseste django-modeltranslation pentru a adauga campuri traductibile la modelele tale, apoi automatizeaza traducerea cu AI folosind TranslateBot.

Pachete de traducere a bazei de date Django

Mai multe pachete terte rezolva problema traducerii bazei de date, fiecare cu o arhitectura diferita.

django-modeltranslation

Adauga coloane specifice limbii direct in tabelele existente. Un camp title devine title_en, title_de, title_fr si asa mai departe. Interogarile raman rapide deoarece totul este in acelasi tabel. Interfata de admin arata toate limbile una langa alta.

Avantaje: Fara JOIN-uri, interogari rapide, acces transparent prin descriptori de camp, ecosistem matur
Dezavantaje: Modificari de schema pentru fiecare limba noua, tabele mai late

django-parler

Creeaza un tabel de traducere separat pentru fiecare model. Tabelul original ramane curat, iar traducerile sunt stocate intr-un tabel asociat legat prin cheie straina.

Avantaje: Schema curata, usor de adaugat limbi fara migratii
Dezavantaje: Necesita JOIN-uri pentru continutul tradus, modele de interogare usor mai complexe

django-translations

Foloseste un singur tabel de traduceri cu o cheie straina generica care indica inapoi catre orice model. Toate traducerile pentru toate modelele merg intr-un singur tabel.

Avantaje: Modificari minime de schema, functioneaza cu orice model
Dezavantaje: Interogarile cu cheie straina generica pot fi lente, API mai putin transparent

Camp JSON manual

Poti stoca traducerile intr-un JSONField:

class Product(models.Model):
    name_translations = models.JSONField(default=dict)
    # {"en": "Running Shoes", "de": "Laufschuhe", "fr": "Chaussures de course"}

Avantaje: Fara dependente suplimentare, flexibil
Dezavantaje: Fara integrare ORM, fara suport admin, totul manual

Pe care ar trebui sa il folosesti?

Pentru majoritatea proiectelor, django-modeltranslation este cea mai buna alegere. Este cel mai matur pachet, are cea mai buna integrare cu admin-ul Django si pastreaza toate datele in acelasi tabel pentru interogari rapide. Compromisul (tabele mai late si o migratie pentru fiecare limba noua) este gestionabil pentru marea majoritate a aplicatiilor. Restul acestui ghid foloseste django-modeltranslation.

Configurarea django-modeltranslation pas cu pas

Pasul 1: Instaleaza pachetul

TranslateBot include django-modeltranslation ca dependenta optionala. Instaleaza ambele deodata:

pip install translatebot-django[modeltranslation]

Sau daca folosesti uv:

uv add --dev translatebot-django[modeltranslation]

Pasul 2: Configureaza setarile Django

Doua lucruri conteaza in settings.py: ordinea aplicatiilor si lista de limbi.

# settings.py

INSTALLED_APPS = [
    'modeltranslation',          # Must be BEFORE django.contrib.admin
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Your apps
    'shop',
    'translatebot_django',
]

LANGUAGE_CODE = 'en'

LANGUAGES = [
    ('en', 'English'),
    ('de', 'German'),
    ('fr', 'French'),
    ('nl', 'Dutch'),
]

Aplicatia modeltranslation trebuie sa fie inaintea django.contrib.admin pentru a putea modifica clasele admin sa afiseze campurile de traducere.

Pasul 3: Inregistreaza modelele pentru traducere

Creeaza un fisier translation.py in fiecare aplicatie care are modele traductibile. Pentru o aplicatie de magazin e-commerce:

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product, Category


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')


@register(Category)
class CategoryTranslationOptions(TranslationOptions):
    fields = ('name', 'description')

Include doar campurile care contin text lizibil pentru oameni. Nu inregistra campuri precum slug, price sau sku.

Pasul 4: Creeaza si ruleaza migratiile

python manage.py makemigrations
python manage.py migrate

Dupa aceasta, tabelul shop_product are coloane noi:

Column	Type
`name`	varchar(200)
`name_en`	varchar(200)
`name_de`	varchar(200)
`name_fr`	varchar(200)
`name_nl`	varchar(200)
`description`	text
`description_en`	text
`description_de`	text
`description_fr`	text
`description_nl`	text
`short_description`	text
`short_description_en`	text
`short_description_de`	text
`short_description_fr`	text
`short_description_nl`	text

Fiecare limba definita in LANGUAGES primeste propria coloana pentru fiecare camp inregistrat.

Problema: Campuri de traducere goale

Acum ai schema pregatita, dar fiecare coloana _de, _fr si _nl este goala. Daca ai 500 de produse cu 3 campuri traductibile si 3 limbi tinta, inseamna 4.500 de campuri goale care asteapta sa fie completate.

Traducerea manuala a acelui continut nu este realista. Chiar si cu un serviciu profesional de traducere, ar trebui sa exporti datele, sa le trimiti, sa astepti livrarea si sa importi rezultatele inapoi. Pentru o echipa mica sau un dezvoltator solo, asta inseamna de obicei ca functionalitatea nu este lansata niciodata.

Aici intervine TranslateBot.

Automatizarea traducerilor cu TranslateBot

Comanda de management translate a TranslateBot poate completa toate acele campuri goale folosind AI. Configureaza mai intai cheia API:

# settings.py

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"  # Fast and cost-effective

Apoi traduce toate modelele inregistrate intr-o limba tinta:

python manage.py translate --target-lang de --models

Acea singura comanda gaseste fiecare model inregistrat cu django-modeltranslation, identifica campurile goale pentru limba tinta si le completeaza cu traduceri generate de AI.

Traduce modele specifice

Daca vrei sa traduci doar produsele si nu categoriile:

python manage.py translate --target-lang de --models Product

Sau mai multe modele specifice:

python manage.py translate --target-lang de --models Product Category

Previzualizare cu dry run

Previzualizeaza intotdeauna inainte de a scrie in baza de date:

python manage.py translate --target-lang de --models --dry-run

Asta iti arata exact ce va fi tradus fara a modifica nicio inregistrare.

Retraduce continutul existent

Implicit, TranslateBot omite campurile care au deja o traducere. Pentru a suprascrie traducerile existente (de exemplu, dupa imbunatatirea modelului AI sau adaugarea de context):

python manage.py translate --target-lang de --models --overwrite

Traduce toate limbile deodata

Daca omiti --target-lang si ai LANGUAGES definit in setari, TranslateBot traduce in toate limbile configurate:

python manage.py translate --models

Cum functioneaza pipeline-ul de traducere

Iata ce se intampla cand rulezi comanda translate.

Descoperire. TranslateBot interogheaza registrul django-modeltranslation pentru a gasi toate modelele inregistrate si campurile lor traductibile.
Detectia sursei. Pentru fiecare inregistrare, citeste continutul sursa. Verifica mai intai campul de baza (de exemplu, name), apoi recurge la primul camp specific limbii care este completat (de exemplu, name_en). Inregistrarile fara continut sursa sunt omise.
Grupare in loturi. Inregistrarile sunt grupate in loturi si trimise furnizorului AI. Aceasta mentine apelurile API eficiente si evita atingerea limitelor de rata.
Traducere. Fiecare lot este tradus folosind modelul AI configurat. Poti folosi orice furnizor LLM suportat de LiteLLM (OpenAI, Anthropic, Google, Azure si multi altii) sau DeepL.
Scrieri atomice. Toate actualizarile bazei de date pentru o sesiune de traducere sunt impachetate intr-o singura tranzactie. Daca ceva nu merge bine, cum ar fi o eroare API sau o incalcare a constrangerilor bazei de date, nu sunt salvate date partiale. Totul sau nimic.

Exemplu complet de workflow

Iata un exemplu complet de la definitia modelului la continutul tradus, folosind un model Product de e-commerce.

Defineste modelul

# shop/models.py

from django.db import models


class Product(models.Model):
    name = models.CharField(max_length=200)
    description = models.TextField()
    short_description = models.CharField(max_length=500, blank=True)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    sku = models.CharField(max_length=50, unique=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

Inregistreaza pentru traducere

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')

Ruleaza migratiile

python manage.py makemigrations shop
python manage.py migrate

Adauga context de traducere (optional)

Creeaza un fisier TRANSLATING.md in radacina proiectului pentru a oferi AI context despre domeniul produselor tale:

# Translation Context

## About This Project
E-commerce store for outdoor sports equipment.

## Terminology
- "trail runners" refers to trail running shoes, not people
- Keep brand names (Nike, Salomon, Arc'teryx) untranslated
- "Gore-Tex" is a brand name, do not translate

## Tone
- Use informal "du" form in German
- Product descriptions should sound enthusiastic but not exaggerated

Traduce

# Preview first
python manage.py translate --target-lang de --models Product --dry-run

# Apply translations
python manage.py translate --target-lang de --models Product

Output:

Translating Product model fields to German (de)...
Found 142 products with untranslated fields
Translating batch 1/15...
Translating batch 2/15...
...
Translating batch 15/15...
Successfully translated 142 products

Verifica in admin

Deschide admin-ul Django si mergi la orice produs. Vei vedea campurile de traducere completate:

Name [de]: Ultraleichte Trail-Laufschuhe
Description [de]: Diese leichten Trail-Laufschuhe bieten hervorragenden Grip...
Short description [de]: Leicht, schnell und griffig auf jedem Untergrund.

Repeta pentru fiecare limba tinta:

python manage.py translate --target-lang fr --models Product
python manage.py translate --target-lang nl --models Product

Sau traduce toate limbile deodata:

python manage.py translate --models Product

Bune practici

Fa o copie de siguranta a bazei de date inainte de a rula traduceri in masa pe productie. TranslateBot foloseste tranzactii atomice, deci o rulare esuata nu va lasa date partiale. Dar avand o copie de siguranta iti ofera o modalitate de a reveni daca calitatea traducerii nu este cea asteptata.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Foloseste dry run mai intai. Ruleaza intotdeauna cu --dry-run inainte de a aplica traducerile pe un model sau o limba noua. Revizuieste output-ul pentru a te asigura ca continutul sursa este detectat corect si traducerile arata rezonabil.

Traduce cate un model pe rand pentru baze de date mari. Aceasta face mai usor de revizuit rezultatele si de rerulat modele specifice daca este necesar.

python manage.py translate --target-lang de --models Product
python manage.py translate --target-lang de --models Category
python manage.py translate --target-lang de --models Article

Adauga context de traducere. Un fisier TRANSLATING.md cu terminologie specifica domeniului si ghiduri de ton imbunatateste semnificativ calitatea traducerii. Acest lucru este deosebit de important pentru domenii specializate precum medicina, dreptul sau produsele tehnice.

Pastreaza limba sursa completata. TranslateBot citeste din campul de baza sau campul limbii sursa. Asigura-te ca fluxul de introducere a datelor completeaza intotdeauna limba sursa. Campurile sursa goale inseamna traduceri goale.

Combina cu traducerea fisierelor PO pentru acoperire completa. Traduce atat string-urile din cod cat si continutul din baza de date:

# Static strings in code and templates
python manage.py makemessages -l de -l fr -l nl
python manage.py translate
python manage.py compilemessages

# Dynamic content in the database
python manage.py translate --models

In acest fel, fiecare string pe care il vad utilizatorii tai, fie ca provine dintr-un template sau din baza de date, este tradus.

Pasi urmatori

Citeste referinta completa a comenzilor pentru toate optiunile disponibile
Configureaza integrarea CI pentru a verifica automat traducerile lipsa
Exploreaza modelele AI suportate pentru a gasi cel mai bun echilibru intre calitate si cost pentru proiectul tau