Jak tłumaczyć zawartość bazy danych Django za pomocą AI

Jesli pracowales z wbudowanym frameworkiem internacjonalizacji (i18n) Django, wiesz, ze dobrze radzi sobie ze statycznymi lancuchami znakow. Owijanie tekstu w gettext() lub uzywanie tagu szablonu {% trans %} wyodrebnia lancuchy do plikow .po, ktore wypelniaja tlumacze. System jest sprawdzony w boju i swietnie dziala dla kodu i szablonow.

Ale co z trescia przechowywana w bazie danych?

Nazwy produktow, tytuly artykulow, opisy kategorii, odpowiedzi na FAQ, tresci generowane przez uzytkownikow. Nic z tego nie znajduje sie w kodzie zrodlowym. Polecenie makemessages Django nigdy tego nie znajdzie, a pliki .po nie pomoga. Jesli Twoja aplikacja serwuje dynamiczna tresc uzytkownikom w wielu jezykach, potrzebujesz innej strategii.

Oto jak to zrobic: uzyj django-modeltranslation, aby dodac tlumaczalne pola do swoich modeli, a nastepnie zautomatyzuj tlumaczenie za pomoca AI przy uzyciu TranslateBot.

Pakiety do tlumaczenia bazy danych Django

Kilka pakietow firm trzecich rozwiazuje problem tlumaczenia bazy danych, kazdy z inna architektura.

django-modeltranslation

Dodaje kolumny specyficzne dla jezyka bezposrednio do istniejacych tabel. Pole title staje sie title_en, title_de, title_fr itd. Zapytania pozostaja szybkie, poniewaz wszystko jest w tej samej tabeli. Interfejs admina pokazuje wszystkie jezyki obok siebie.

Zalety: Brak JOINow, szybkie zapytania, przezroczysty dostep przez deskryptory pol, dojrzaly ekosystem
Wady: Zmiany schematu dla kazdego nowego jezyka, szersze tabele

django-parler

Tworzy osobna tabele tlumaczen dla kazdego modelu. Oryginalna tabela pozostaje czysta, a tlumaczenia sa przechowywane w powiazanej tabeli polaczonej kluczem obcym.

Zalety: Czysty schemat, latwe dodawanie jezykow bez migracji
Wady: Wymaga JOINow dla przetlumaczonej tresci, nieco bardziej zlozone wzorce zapytan

django-translations

Uzywa pojedynczej tabeli tlumaczen z generycznym kluczem obcym wskazujacym na dowolny model. Wszystkie tlumaczenia dla wszystkich modeli trafiaja do jednej tabeli.

Zalety: Minimalne zmiany schematu, dziala z kazdym modelem
Wady: Zapytania z generycznym kluczem obcym moga byc wolne, mniej przejrzyste API

Reczne pole JSON

Mozesz przechowywac tlumaczenia w JSONField:

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

Zalety: Brak dodatkowych zaleznosci, elastycznosc
Wady: Brak integracji z ORM, brak wsparcia admina, wszystko recznie

Ktory wybrac?

Dla wiekszosci projektow django-modeltranslation to najlepszy wybor. To najbardziej dojrzaly pakiet, ma najlepsza integracje z adminem Django i przechowuje wszystkie dane w tej samej tabeli dla szybkich zapytan. Kompromis (szersze tabele i migracja dla kazdego nowego jezyka) jest do ogarniecia dla zdecydowanej wiekszosci aplikacji. Reszta tego poradnika uzywa django-modeltranslation.

Konfiguracja django-modeltranslation krok po kroku

Krok 1: Zainstaluj pakiet

TranslateBot dolacza django-modeltranslation jako opcjonalna zaleznosc. Zainstaluj oba naraz:

pip install translatebot-django[modeltranslation]

Lub jesli uzywasz uv:

uv add --dev translatebot-django[modeltranslation]

Krok 2: Skonfiguruj ustawienia Django

Dwie rzeczy sa wazne w settings.py: kolejnosc aplikacji i lista jezykow.

# 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'),
]

Aplikacja modeltranslation musi byc przed django.contrib.admin, aby mogla zalatac klasy admina w celu wyswietlania pol tlumaczen.

Krok 3: Zarejestruj modele do tlumaczenia

Utworz plik translation.py w kazdej aplikacji, ktora ma tlumaczalne modele. Dla aplikacji sklepu 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')

Dolaczaj tylko pola zawierajace tekst czytelny dla czlowieka. Nie rejestruj pol takich jak slug, price czy sku.

Krok 4: Utworz i uruchom migracje

python manage.py makemigrations
python manage.py migrate

Po tym tabela shop_product ma nowe kolumny:

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

Kazdy jezyk zdefiniowany w LANGUAGES dostaje wlasna kolumne dla kazdego zarejestrowanego pola.

Problem: Puste pola tlumaczen

Masz juz schemat, ale kazda kolumna _de, _fr i _nl jest pusta. Jesli masz 500 produktow z 3 tlumaczalnymi polami i 3 jezykami docelowymi, to 4500 pustych pol czekajacych na wypelnienie.

Reczne tlumaczenie tej tresci nie jest realistyczne. Nawet korzystajac z profesjonalnej uslugi tlumaczeniowej, musisz wyeksportowac dane, wyslac je, czekac na dostawe i zaimportowac wyniki z powrotem. Dla malego zespolu lub samodzielnego programisty oznacza to zwykle, ze funkcja nigdy nie zostaje wydana.

Tu wlasnie wkracza TranslateBot.

Automatyzacja tlumaczen za pomoca TranslateBot

Polecenie zarzadzania translate TranslateBot moze wypelnic wszystkie puste pola za pomoca AI. Najpierw skonfiguruj klucz API:

# settings.py

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

Nastepnie przetlumacz wszystkie zarejestrowane modele na jezyk docelowy:

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

To pojedyncze polecenie znajduje kazdy model zarejestrowany w django-modeltranslation, identyfikuje pola puste dla jezyka docelowego i wypelnia je tlumaczeniami wygenerowanymi przez AI.

Tlumaczenie konkretnych modeli

Jesli chcesz przetlumaczyc tylko produkty, a nie kategorie:

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

Lub kilka konkretnych modeli:

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

Podglad za pomoca dry run

Zawsze sprawdz podglad przed zapisem do bazy danych:

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

To pokazuje dokladnie, co zostanie przetlumaczone, bez modyfikowania jakichkolwiek rekordow.

Ponowne tlumaczenie istniejacej tresci

Domyslnie TranslateBot pomija pola, ktore juz maja tlumaczenie. Aby nadpisac istniejace tlumaczenia (na przyklad po ulepszeniu modelu AI lub dodaniu kontekstu):

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

Tlumaczenie wszystkich jezykow naraz

Jesli pominiesz --target-lang i masz zdefiniowane LANGUAGES w ustawieniach, TranslateBot tlumaczy na wszystkie skonfigurowane jezyki:

python manage.py translate --models

Jak dziala pipeline tlumaczenia

Oto co sie dzieje po uruchomieniu polecenia translate.

Odkrywanie. TranslateBot odpytuje rejestr django-modeltranslation, aby znalezc wszystkie zarejestrowane modele i ich tlumaczalne pola.
Wykrywanie zrodla. Dla kazdego rekordu odczytuje tresc zrodlowa. Najpierw sprawdza pole bazowe (np. name), a nastepnie cofa sie do pierwszego wypelnionego pola specyficznego dla jezyka (np. name_en). Rekordy bez tresci zrodlowej sa pomijane.
Grupowanie w partie. Rekordy sa grupowane w partie i wysylane do dostawcy AI. Dzieki temu wywolania API sa wydajne i nie przekraczaja limitow szybkosci.
Tlumaczenie. Kazda partia jest tlumaczona za pomoca skonfigurowanego modelu AI. Mozesz uzyc dowolnego dostawcy LLM wspieranego przez LiteLLM (OpenAI, Anthropic, Google, Azure i wielu innych) lub DeepL.
Atomowe zapisy. Wszystkie aktualizacje bazy danych dla sesji tlumaczenia sa opakowane w pojedyncza transakcje. Jesli cos pojdzie nie tak, jak blad API lub naruszenie ograniczenia bazy danych, zadne czesciowe dane nie zostana zapisane. Wszystko albo nic.

Kompletny przyklad workflow

Oto pelny przyklad od definicji modelu do przetlumaczonej tresci, z uzyciem modelu Product w e-commerce.

Zdefiniuj model

# 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

Zarejestruj do tlumaczenia

# shop/translation.py

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


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

Uruchom migracje

python manage.py makemigrations shop
python manage.py migrate

Dodaj kontekst tlumaczenia (opcjonalnie)

Utworz plik TRANSLATING.md w katalogu glownym projektu, aby dac AI kontekst dotyczacy domeny Twoich produktow:

# 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

Przetlumacz

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

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

Wynik:

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

Zweryfikuj w adminie

Otworz admina Django i przejdz do dowolnego produktu. Zobaczysz wypelnione pola tlumaczen:

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

Powtorz dla kazdego jezyka docelowego:

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

Lub przetlumacz wszystkie jezyki naraz:

python manage.py translate --models Product

Najlepsze praktyki

Zrob kopie zapasowa bazy danych przed uruchomieniem masowych tlumaczen na produkcji. TranslateBot uzywa transakcji atomowych, wiec nieudane uruchomienie nie pozostawi czesciowych danych. Ale posiadanie kopii zapasowej daje mozliwosc cofniecia zmian, jesli jakosc tlumaczenia nie spelni oczekiwan.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Najpierw uzyj dry run. Zawsze uruchamiaj z --dry-run przed zastosowaniem tlumaczen do nowego modelu lub jezyka. Przejrzyj wynik, aby upewnic sie, ze tresc zrodlowa jest prawidlowo wykrywana, a tlumaczenia wygladaja rozsadnie.

Tlumacz jeden model na raz w przypadku duzych baz danych. Ulatwia to przegladanie wynikow i ponowne uruchamianie konkretnych modeli w razie potrzeby.

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

Dodaj kontekst tlumaczenia. Plik TRANSLATING.md z terminologia specyficzna dla domeny i wytycznymi dotyczacymi tonu znaczaco poprawia jakosc tlumaczenia. Jest to szczegolnie wazne dla specjalistycznych dziedzin, takich jak medycyna, prawo czy produkty techniczne.

Utrzymuj wypelniony jezyk zrodlowy. TranslateBot czyta z pola bazowego lub pola jezyka zrodlowego. Upewnij sie, ze Twoj workflow wprowadzania danych zawsze wypelnia jezyk zrodlowy. Puste pola zrodlowe oznaczaja puste tlumaczenia.

Polacz z tlumaczeniem plikow PO dla pelnego pokrycia. Przetlumacz zarowno lancuchy w kodzie, jak i tresc bazy danych:

# 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

W ten sposob kazdy lancuch, ktory widza Twoi uzytkownicy, czy to z szablonu, czy z bazy danych, jest przetlumaczony.

Nastepne kroki

Przeczytaj pelna dokumentacje polecen ze wszystkimi dostepnymi opcjami
Skonfiguruj integracje CI, aby automatycznie sprawdzac brakujace tlumaczenia
Poznaj wspierane modele AI, aby znalezc najlepsza rownowage miedzy jakoscia a kosztem dla swojego projektu