Django i18n: .po Dosyası Çevirisini Otomatikleştirmenin Tam Kılavuzu

Birden fazla dilde bir Django uygulaması yayinladiysan, bu sureci biliyorsundur. String'lerinizi gettext() ile sararsiniz, makemessages calistirirsiniz, yuzlerce girdi iceren bir .po dosyasi acarsiniz ve satir satir ceviri yapmaya baslarsiniz. Iki dil ve elli string icin bu katlanilabilir. Alti dil ve bes yuz string icin, geri alamayacaginiz tam bir is gunu.

Bu rehber Django'nun uluslararasilastirma (i18n) hattini bastan sona kapsar, nerede bozuldugunu aciklar ve agri veren kismin AI destekli ceviri ile nasil otomatiklestirilebilecegini gosterir.

Standart Django i18n Is Akisi

Django'nun yerlesik i18n sistemi iyi tasarlanmistir. Temel dongu soyle gorunur:

Adim 1: Python kodunuzda ve sablonlarinizda ceviri icin string'leri isaretleyin:

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>

Adim 2: String'leri .po dosyalarina cikartin:

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

Bu, tum kod tabaninizi tarar ve her dil icin cevrilebilebilir her string'i iceren bir .po dosyasi olusturur:

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

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

Adim 3: Her bos msgstr'yi elle cevirin.

Adim 4: Tamamlanan .po dosyalarini ikili .mo dosyalarina derleyin:

python manage.py compilemessages

Adim 1, 2 ve 4 hizlidir. Adim 3, surecin cokmeye basladigi yerdir.

Manuel Ceviri Neden Olceklenmez

Tipik bir Django uygulamasinda 200 ile 2.000 arasinda cevrilebilebilir string bulunur. Bunu hedef dil sayisiyla carpin ve ciddi bir zaman taahhudunle karsi karsiya kalirsiniz.

Bu teorik bir sikayet degildir. Bilinen bir Django Forum konusunda, bir gelistirici .po dosyasi basina 8+ saat manuel ceviri yaptigini bildirmistir. Bir Django cekirdek katilimcisi, topluluk tarafindan gonderilen cevirileri tek bir surume dahil etmek icin 10 saatten fazla harcadigini, bunun cogunun inceleme, bicimlendirme duzeltmeleri ve bozuk yer tutuculari onarmak oldugunu anlatmistir.

Sorunlar zamanla birikir:

• Yer tutucular bozulur. Welcome, %(name)s! gibi bir string'i Google Translate'e kopyalayin, siklikla Willkommen, %(Name)s! veya Bienvenue, %(nom)s! geri alirsiniz. Bu ince bozulma calisma zamani cokmelere neden olur.
• Tutarlilik kayar. Sozluk olmadan, "dashboard" bir dosyada "Instrumententafel", digerinde "Dashboard" olarak cevrilir. Uc ay sonra, hangisinin kasitli oldugunu kimse hatirlayamaz.
• Sprint'ler string ekler. Her ozellik dali yeni cevrilebilebilir string'ler ekler. Gecen ceyrek tam bir ceviri icin odeme yaptiysaniz bile, simdi .po dosyalariniza dagilmis 40 cevrilmemis girdiniz var.
• AI asistanlar bir kez yardim eder. Bir .po dosyasini ChatGPT veya Claude'a yapistirip iyi sonuclar alabilirsiniz. Ama sonraki sprint'te, 15 yeni string belirdiginde, sifirdan komut yaziyorsunuz, tum dosyayi yeniden ceviriyorsunuz ve zaten olanla tutarli kalmasini umuyorsunuz.

Temel neden, cevirinin artirimli, tekrarlanabilir bir surec yerine tek seferlik bir olay olarak ele alinmasidir.

AI ile Ceviriyi Otomatiklestirme

Fikir basittir: bir insanin her .po dosyasini acip msgstr degerlerini doldurmasi yerine, bir arac dosyayi okur, cevrilmemis string'leri bir AI modeline veya ceviri API'sine gonderir, sonuclari geri yazar ve diger her seyi (yorumlar, dosya yapisi, yer tutucular, cogul bicimleri) korur.

TranslateBot Django tam olarak bunu yapan acik kaynakli bir pakettir. Django'nun yonetim komutu sistemine entegre olur, bu nedenle zaten sahip oldugunuz is akisina uyar.

Adim Adim Kurulum

1. Paketi Yukleyin

pip install translatebot-django

Veya, uv kullaniyorsaniz (onerilir):

uv add --dev translatebot-django

Gelistirme bagimliligi olarak yuklemek kasitlidir. TranslateBot'a yalnizca ceviri olusturulurken ihtiyaciniz var, uretimde calisma zamaninda degil.

2. INSTALLED_APPS'e Ekleyin

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

3. AI Saglayicinizi Yapilandirin

# settings.py
import os

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

TranslateBot arka planda LiteLLM kullanir, bu da tek bir string'i degistirerek 100'den fazla modelden herhangi birine gecebileceginiz anlamina gelir:

DeepL icin, ekstrayi yukleyin: pip install translatebot-django[deepl]. DeepL'in ucretsiz katmani ayda 500.000 karakter ucretsiz saglar, bu cogu kucuk-orta olcekli proje icin yeterlidir.

4. Dillerinizi Tanimlayin

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

5. Ceviriyi Calistirin

python manage.py translate

Bu kadar. TranslateBot projenizi .po dosyalari icin tarar, cevrilmemis girdileri tespit eder, optimize edilmis gruplar halinde yapilandirilmis AI modeline gonderir ve sonuclari geri yazar. Mevcut ceviriler dokunulmaz.

Tek bir dili cevirmek icin:

python manage.py translate --target-lang nl

Cikti soyle gorunur:

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

6. Her Zamanki Gibi Derleyin

python manage.py compilemessages

Tam is akisiniz artik:

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

Uc komut. Her dil. Her sprint.

Tasarim Geregi Artirimli

Tekrarlanabilir bir is akisi icin en onemli ozellik artirimli ceviridir. TranslateBot yalnizca msgstr'nin bos oldugu girdileri cevirir. 500 string'iniz varsa ve bu sprint'te 15'i yeniyse, yalnizca o 15 API'ye gonderilir.

Bu pratik nedenlerle onemlidir:

1. Maliyet. Yalnizca yeni string'ler icin odeme yaparsiniz, tum dosya icin degil.
2. Hiz. 15 string'i cevirmek saniyeler alir, dakikalar degil.
3. Kararlilik. Zaten inceleyip onayladiginiz ceviriler asla uzerine yazilmaz (acikca --overwrite gecirmedikce).

Yer Tutucu Guvenligi

Django cesitli yer tutucu bicimlerini kullanir: %(name)s, %s, %d, {0}, {name} ve <strong> veya <a href="..."> gibi satir ici HTML etiketleri. Bunlardan herhangi biri ceviride bozulursa, calisma zamani hatalari veya bozuk isaratleme elde edersiniz.

TranslateBot AI modeline tum yer tutucu bicimlerini koruma talimati verir ve ciktiyi dogrular. Su gibi bir string:

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

Hollandacaya su sekilde cevrilir:

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

Her yer tutucu saglam kalir.

TRANSLATING.md ile Kalite Kontrolu

AI modelleri baglami anladiklarinda daha iyi ceviri yapar. TranslateBot proje kokunde TRANSLATING.md dosyasini arar ve icerigini her ceviri istegine dahil eder.

# 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"

Bu dosya kodunuzla birlikte surum kontrolundedir, bu nedenle tum ekip ayni ceviri baglamini paylesir.

Commit'lemeden Once Onizleme

--dry-run bayragi herhangi bir API cagrisi yapmadan veya dosyalari degistirmeden tam olarak neyin cevirilecegini gosterir:

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

CI/CD Entegrasyonu

Zorunluluk olmadan cevirilerin eskimesi kacinilmazdir. TranslateBot, CI islem hatlari icin tasarlanmis bir check_translations yonetim komutu icerir:

# .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

--makemessages bayragi once makemessages -a --no-obsolete calistirir, kontrol etmeden once .po dosyalarinin guncel kaynak kodu yansitmasini saglar. Herhangi bir girdi cevrilmemis veya bulaniksa, komut kod 1 ile cikar ve derlemeyi basarisiz kilar:

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

Tipik gelistirici is akisi su olur:

1. Ozellik dalinda yeni cevrilebilebilir string'ler ekleyin.
2. CI basarisiz olur cunku bu string'ler cevrilmemistir.
3. Yerel olarak python manage.py translate calistirin.
4. Guncellenmis .po dosyalarini commit'leyin.
5. CI basarili olur.

Ceviriler asla sessizce senkronizasyondan cikmaz.

Veritabani Icerigini Cevirme

Uygulamaniz veritabaninda cevrilebilebilir icerik sakliyorsa (urun adlari, blog yazisi basliklari, kategori etiketleri), TranslateBot django-modeltranslation ile de entegre olur:

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

Ayni artirimli mantik gecerlidir: yalnizca hedef dil degerinin bos oldugu alanlar cevrilir.

Maliyet Karsilastirmasi

En yaygin sorulardan biri, AI cevirinin alternatiflere kiyasla maliyet etkin olup olmadigidir. 5 dilde 500 cevrilebilebilir string'e sahip bir proje icin yaklasik karsilastirma:

Rakamlar string sayisina ve hedef dillere gore degisir, ancak buyukluk sirasi farki tutarlidir. Devam eden bakim icin (her sprint'te eklenen 20-50 yeni string'in cevirisi), AI maliyeti temelde sifirdir.

En Iyi Uygulamalar

--dry-run ile baslayin. Ilk gercek ceviri calismanizdan once, ne olacagini onizleyin.

Cevirmeden once .po dosyalarini commit'leyin. Bir sey ters giderse, git checkout sizi aninda temiz duruma geri getirir.

Ilk gunden TRANSLATING.md yazin. Proje aciklamaniz ve birkac terminoloji kuraliyla kisa bir dosya bile ceviri kalitesini olculebilir sekilde iyilestirir.

CI'ye check_translations ekleyin. Bu tek adim, en yaygin i18n basarisizlik modunu onler: ceviri icin isaretlenmis ancak hic cevirilmemis string'ler.

Maliyet verimliligi icin gpt-4o-mini veya DeepL kullanin. GPT-4o veya Claude gibi premium modelleri hassasiyetin onemli oldugu projeler icin saklayin.

Kritik string'leri gozden gecirin. AI cevirileri cogu UI metni icin yeterince iyidir, ancak yasal olarak baglayici, guvenlik acisinden kritik veya yuksek riskli baglamda musteriye yonelik her seyi ana dili konusucusuna inceletin.

Saatlerden Saniyelere

Django'nun i18n cercevesi cevirileri cikarma ve derlemede mukemmeldir. Bosluk her zaman ceviri adiminin kendisinde olmustur — birden fazla dilde yuzlerce msgstr degerini doldurmanin sikici, hataya acik isi.

TranslateBot bu boslugu kapatir. Yukleyin, bir AI saglayiciya yonlendirin ve bir komut calistirin. Yeni string'ler cevrilir. Mevcut string'ler dokunulmaz. Yer tutucular saglam kalir. CI kacani yakalar.

.po dosyalariniz bir angaryadan cikip derlemenin bir parcasi haline gelir.

pip install translatebot-django

translatebot.dev adresinde baslayin.