Django Veritabanı İçeriğini AI ile Çevirme

Django'nun yerleşik uluslararasılaştırma (i18n) framework'ü ile çalıştıysanız, statik stringleri iyi yönettiğini bilirsiniz. Metni gettext() ile sarmak veya {% trans %} template etiketini kullanmak, stringleri .po dosyalarına çıkarır ve çevirmenlerin doldurmasını sağlar. Sistem savaşta test edilmiştir ve kod ile templateler için harika çalışır.

Peki veritabanınızda saklanan içerik ne olacak?

Ürün adları, makale başlıkları, kategori açıklamaları, SSS yanıtları, kullanıcı tarafından oluşturulan içerik. Bunların hiçbiri kaynak kodunuzda bulunmaz. Django'nun makemessages komutu bunları asla bulamaz ve .po dosyaları burada size yardımcı olamaz. Uygulamanız birden fazla dilde kullanıcılara dinamik içerik sunuyorsa, farklı bir stratejiye ihtiyacınız var.

İşte nasıl yapılacağı: modellerinize çevrilebilir alanlar eklemek için django-modeltranslation kullanın, ardından TranslateBot ile AI kullanarak çeviriyi otomatikleştirin.

Django Veritabanı Çeviri Paketleri

Birkaç üçüncü parti paket, veritabanı çeviri sorununu farklı mimarilerle çözer.

django-modeltranslation

Mevcut tablolarınıza doğrudan dile özgü sütunlar ekler. Bir title alanı title_en, title_de, title_fr ve benzeri olur. Her şey aynı tabloda olduğu için sorgular hızlı kalır. Yönetim arayüzü tüm dilleri yan yana gösterir.

Artıları: JOIN yok, hızlı sorgular, alan tanımlayıcıları üzerinden şeffaf erişim, olgun ekosistem
Eksileri: Her yeni dil için şema değişiklikleri, daha geniş tablolar

django-parler

Her model için ayrı bir çeviri tablosu oluşturur. Orijinal tablo temiz kalır ve çeviriler yabancı anahtar ile bağlanan ilişkili tabloda saklanır.

Artıları: Temiz şema, migrasyon olmadan dil ekleme kolaylığı
Eksileri: Çevrilen içerik için JOIN gerekir, biraz daha karmaşık sorgu kalıpları

django-translations

Herhangi bir modele işaret eden genel yabancı anahtarlı tek bir çeviri tablosu kullanır. Tüm modellerin tüm çevirileri tek bir tabloya gider.

Artıları: Minimum şema değişiklikleri, herhangi bir modelle çalışır
Eksileri: Genel yabancı anahtar sorguları yavaş olabilir, daha az şeffaf API

Manuel JSON Alanı

Çevirileri JSONField içinde saklayabilirsiniz:

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

Artıları: Ekstra bağımlılık yok, esnek
Eksileri: ORM entegrasyonu yok, yönetim desteği yok, her şey manuel

Hangisini Kullanmalısınız?

Çoğu proje için django-modeltranslation en iyi seçimdir. En olgun paket, en iyi Django yönetim entegrasyonuna sahip ve hızlı sorgular için tüm verileri aynı tabloda tutar. Ödünleşim (daha geniş tablolar ve her yeni dil için bir migrasyon) uygulamaların büyük çoğunluğu için yönetilebilir. Bu kılavuzun geri kalanı django-modeltranslation kullanır.

django-modeltranslation'ı Adım Adım Kurma

Adım 1: Paketi Kurun

TranslateBot, django-modeltranslation'ı isteğe bağlı bağımlılık olarak paketler. İkisini birden kurun:

pip install translatebot-django[modeltranslation]

Veya uv kullanıyorsanız:

uv add --dev translatebot-django[modeltranslation]

Adım 2: Django Ayarlarını Yapılandırın

settings.py'de iki şey önemlidir: uygulama sırası ve dil listesi.

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

modeltranslation uygulaması django.contrib.admin'den önce gelmelidir, böylece çeviri alanlarını göstermek için yönetim sınıflarını yamalayabilir.

Adım 3: Çeviri İçin Modelleri Kaydedin

Çevrilebilir modelleri olan her uygulamada bir translation.py dosyası oluşturun. Bir e-ticaret mağaza uygulaması için:

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

Yalnızca insan tarafından okunabilir metin içeren alanları ekleyin. slug, price veya sku gibi alanları kaydetmeyin.

Adım 4: Migrasyonları Oluşturun ve Çalıştırın

python manage.py makemigrations
python manage.py migrate

Bundan sonra shop_product tablonuzda yeni sütunlar olur:

Sütun	Tür
`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

LANGUAGES'da tanımladığınız her dil, kayıtlı her alan için kendi sütununu alır.

Sorun: Boş Çeviri Alanları

Artık şemanız hazır, ancak her _de, _fr ve _nl sütunu boş. 3 çevrilebilir alan ve 3 hedef dile sahip 500 ürününüz varsa, doldurulmayı bekleyen 4.500 boş alan var.

Bu içeriği manuel olarak çevirmek gerçekçi değil. Profesyonel bir çeviri hizmeti ile bile verileri dışa aktarmanız, göndermeniz, teslimini beklemeniz ve sonuçları geri aktarmanız gerekir. Küçük bir ekip veya tek başına çalışan bir geliştirici için bu genellikle özelliğin hiçbir zaman yayınlanmayacağı anlamına gelir.

İşte burada TranslateBot devreye girer.

TranslateBot ile Çevirileri Otomatikleştirme

TranslateBot'un translate yönetim komutu, AI kullanarak tüm bu boş alanları doldurabilir. Önce API anahtarınızı yapılandırın:

# settings.py

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

Ardından tüm kayıtlı modelleri hedef dile çevirin:

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

Bu tek komut, django-modeltranslation ile kayıtlı her modeli bulur, hedef dil için boş alanları belirler ve bunları AI tarafından oluşturulan çevirilerle doldurur.

Belirli Modelleri Çevirin

Yalnızca ürünleri çevirmek istiyorsanız, kategorileri değil:

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

Veya birden fazla belirli model:

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

Dry Run ile Önizleme

Veritabanına yazmadan önce her zaman önizleme yapın:

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

Bu, herhangi bir kaydı değiştirmeden neyin çevrileceğini tam olarak gösterir.

Mevcut İçeriği Yeniden Çevirin

Varsayılan olarak TranslateBot, zaten çevirisi olan alanları atlar. Mevcut çevirilerin üzerine yazmak için (örneğin, AI modelinizi iyileştirdikten veya bağlam ekledikten sonra):

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

Tüm Dilleri Bir Seferde Çevirin

--target-lang'ı atlarsanız ve ayarlarınızda LANGUAGES tanımlıysa, TranslateBot yapılandırılmış tüm dillere çevirir:

python manage.py translate --models

Çeviri Pipeline'ı Nasıl Çalışır

Çeviri komutunu çalıştırdığınızda olan budur.

Keşif. TranslateBot, tüm kayıtlı modelleri ve çevrilebilir alanlarını bulmak için django-modeltranslation kayıt defterini sorgular.
Kaynak tespiti. Her kayıt için kaynak içeriği okur. Önce temel alanı kontrol eder (örn., name), ardından doldurulmuş ilk dile özgü alana geri döner (örn., name_en). Kaynak içeriği olmayan kayıtlar atlanır.
Gruplama. Kayıtlar gruplar halinde toplanır ve AI sağlayıcısına gönderilir. Bu, API çağrılarını verimli tutar ve hız sınırlarına ulaşmayı önler.
Çeviri. Her grup, yapılandırılmış AI modeli kullanılarak çevrilir. LiteLLM tarafından desteklenen herhangi bir LLM sağlayıcısını (OpenAI, Anthropic, Google, Azure ve daha birçoğu) veya DeepL kullanabilirsiniz.
Atomik yazma. Bir çeviri çalışmasının tüm veritabanı güncellemeleri tek bir işleme sarılır. API hatası veya veritabanı kısıtlama ihlali gibi bir şey yanlış giderse, kısmi veri kaydedilmez. Ya hep ya hiç.

Tam İş Akışı Örneği

İşte model tanımından çevrilmiş içeriğe kadar tam bir örnek, bir e-ticaret Product modeli kullanarak.

Modeli Tanımlayın

# 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

Çeviri İçin Kaydedin

# shop/translation.py

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


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

Migrasyonları Çalıştırın

python manage.py makemigrations shop
python manage.py migrate

Çeviri Bağlamı Ekleyin (İsteğe Bağlı)

AI'ya ürün alanınız hakkında bağlam vermek için proje kök dizininizde bir TRANSLATING.md dosyası oluşturun:

# 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

Çevirin

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

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

Çıktı:

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

Yönetim Panelinde Doğrulayın

Django yönetim panelini açın ve herhangi bir ürüne gidin. Çeviri alanlarının doldurulduğunu göreceksiniz:

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

Her hedef dil için tekrarlayın:

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

Veya tüm dilleri bir seferde çevirin:

python manage.py translate --models Product

En İyi Uygulamalar

Üretim ortamında toplu çeviriler çalıştırmadan önce veritabanınızı yedekleyin. TranslateBot atomik işlemler kullanır, bu yüzden başarısız bir çalışma kısmi veri bırakmaz. Ancak yedek, çeviri kalitesi beklediğiniz gibi değilse geri dönme yolu sağlar.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Önce dry run kullanın. Yeni bir model veya dile çeviri uygulamadan önce her zaman --dry-run ile çalıştırın. Kaynak içeriğin doğru tespit edildiğinden ve çevirilerin makul göründüğünden emin olmak için çıktıyı inceleyin.

Büyük veritabanları için bir seferde bir model çevirin. Bu, sonuçları incelemeyi ve gerektiğinde belirli modelleri yeniden çalıştırmayı kolaylaştırır.

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

Çeviri bağlamı ekleyin. Alana özgü terminoloji ve ton yönergeleri içeren bir TRANSLATING.md dosyası çeviri kalitesini önemli ölçüde artırır. Bu özellikle tıp, hukuk veya teknik ürünler gibi uzmanlaşmış alanlar için önemlidir.

Kaynak dilinizi dolu tutun. TranslateBot temel alandan veya kaynak dil alanından okur. Veri girişi iş akışınızın her zaman kaynak dili doldurduğundan emin olun. Boş kaynak alanlar boş çeviriler anlamına gelir.

Tam kapsam için PO dosyası çevirisi ile birleştirin. Hem kod stringlerinizi hem de veritabanı içeriğinizi çevirin:

# 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

Bu şekilde kullanıcılarınızın gördüğü her string, ister bir templateden ister veritabanından gelsin, çevrilmiş olur.

Sonraki Adımlar

Mevcut tüm seçenekler için tam komut referansını okuyun
Eksik çevirileri otomatik kontrol etmek için CI entegrasyonunu kurun
Projeniz için kalite ve maliyet arasındaki en iyi dengeyi bulmak için desteklenen AI modellerini keşfedin