Django i18n ve AI ile Çeviri: Eksiksiz Kurulum Rehberi

Django, GNU gettext üzerine kurulu olgun bir uluslararasılaştırma (i18n) çerçevesiyle birlikte gelir. Bu temeli AI destekli çeviriyle birleştirdiğinizde, tek kişilik bir projeden çok yerel üretim uygulamasına kadar ölçeklenen ve sizi manuel çeviri işlerinde boğmayan bir iş akışı elde edersiniz.

Bu rehber sürecin tamamını ele alır: Django'yu i18n için yapılandırma, dizeleri işaretleme, .po dosyalarını yönetme, AI ile çeviriyi otomatikleştirme ve her şeyi CI/CD pipeline'ına bağlama.

Temel Çıkarımlar

Django'nun i18n sistemi GNU gettext kullanır — dizeler Python ve şablonlarda işaretlenir, .po dosyalarına çıkarılır ve çalışma zamanı kullanımı için ikili .mo dosyalarına derlenir.
AI çevirisi, .po dosyası çevirisini otomatikleştirebilir — makine çevirisi API'leri çevrilmemiş girdileri toplu olarak işler; günlerce süren manuel çalışmayı dakikalara indirir.
Kalite inceleme adımı şarttır — AI tarafından üretilen çeviriler, özellikle kullanıcıya yönelik içerik için üretim dağıtımından önce anadil konuşanlar tarafından gözden geçirilmelidir.
CI/CD entegrasyonu döngüyü kapatır — otomatik pipeline'lar yeni dizeleri çıkarabilir, çevirebilir, mesaj dosyalarını derleyebilir ve manuel müdahale olmaksızın dağıtabilir.
Better i18n yönetilen bir iş akışı sunar — özel komut dosyaları oluşturmak yerine .po dosyalarını senkronize edebilir, çevirileri yönetebilir ve tüm yaşam döngüsünü tek bir platformdan otomatikleştirebilirsiniz.

Django i18n Nedir?

Django i18n, web uygulamanızı birden fazla dile çevirmenizi sağlayan Django'nun yerleşik uluslararasılaştırma çerçevesidir. GNU gettext'i sararak dize çıkarma, çeviri dosyası yönetimi ve çalışma zamanı dil değiştirme işlevleri sunar; bunların tümü Django'nun şablonlarına, formlarına ve URL yönlendirmesine entegre edilmiştir.

Django, uluslararasılaştırmayı (i18n) yerelleştirmeden (l10n) ayırır. Uluslararasılaştırma, kodunuzu birden fazla dili destekleyecek şekilde hazırlama sürecidir. Yerelleştirme ise içeriği gerçekten çevirme ve belirli bir yerel ayara göre biçimleri uyarlama sürecidir. Django her ikisini de django.utils.translation modülü ve gettext araç zinciri aracılığıyla yönetir.

Çerçeve şunların çevirisini destekler:

Görünümlerde, modellerde ve formlarda Python dizeleri
Yerleşik şablon etiketleri kullanan şablon içeriği
Yerel ayar önekli yönlendirme için URL kalıpları
django.utils.formats aracılığıyla tarih, saat, sayı ve para birimi biçimlendirmesi

Resmi başvuru için Django uluslararasılaştırma belgelerine bakın.

Django'yu Uluslararasılaştırma için Yapılandırma

Herhangi bir dizeyi çeviri için işaretlemeden önce Django ayarlarını yapılandırmanız ve gerekli ara yazılımı yüklemeniz gerekir.

Ayarları Yapılandırın

settings.py dosyanızı açın ve aşağıdakileri ayarlayın:

# settings.py

from django.utils.translation import gettext_lazy as _

# Uygulama için varsayılan dil
LANGUAGE_CODE = "en"

# Uluslararasılaştırma çerçevesini etkinleştir
USE_I18N = True

# Tarihlerin, sayıların vb. yerelleştirilmiş biçimlendirmesini etkinleştir
USE_L10N = True

# Saat dilimine duyarlı datetime'ları etkinleştir
USE_TZ = True

# Uygulamanızın desteklediği diller
LANGUAGES = [
    ("en", _("English")),
    ("es", _("Spanish")),
    ("fr", _("French")),
    ("de", _("German")),
    ("ja", _("Japanese")),
]

# Django'nun çeviri dosyalarını aradığı yer
LOCALE_PATHS = [
    BASE_DIR / "locale",
]

Ayrıca ara yazılım yığınınızda LocaleMiddleware'e ihtiyacınız vardır. SessionMiddleware'den sonra ve CommonMiddleware'den önce gelmelidir:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.locale.LocaleMiddleware",  # Buraya gelmelidir
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

locale dizin yapısını oluşturun:

mkdir -p locale/{es,fr,de,ja}/LC_MESSAGES

Çeviri için Dizeleri İşaretleme

Django, çevrilebilir dizeleri işaretlemek için iki ana işlev sağlar:

gettext() (_() olarak takma adlandırılmış) — dizeyi çalışma zamanında hemen çevirir
gettext_lazy() (yine _() olarak takma adlandırılmış) — çeviriyi dize oluşturulana kadar erteler; model alanları ve form etiketleri gibi modül düzeyindeki kod için gereklidir

Görünümlerde (gettext kullanın):

from django.utils.translation import gettext as _

def dashboard_view(request):
    welcome_message = _("Welcome to your dashboard")
    context = {
        "title": _("Dashboard"),
        "welcome": welcome_message,
    }
    return render(request, "dashboard.html", context)

Modellerde (gettext_lazy kullanın):

from django.db import models
from django.utils.translation import gettext_lazy as _

class Article(models.Model):
    title = models.CharField(
        max_length=200,
        verbose_name=_("Title"),
    )
    body = models.TextField(
        verbose_name=_("Body"),
        help_text=_("The main content of the article."),
    )
    created_at = models.DateTimeField(
        auto_now_add=True,
        verbose_name=_("Created at"),
    )

    class Meta:
        verbose_name = _("Article")
        verbose_name_plural = _("Articles")

    def __str__(self):
        return self.title

Ayrımın önemi vardır: gettext_lazy, dize gerçekte görüntülendiğinde doğru dile çözümlenen tembel bir dize vekili döndürür. Model tanımları içe aktarma zamanında bir kez değerlendirilir; bu nedenle orada gettext kullanmak, içe aktarma sırasında etkin olan dili kalıcı olarak sabitler.

Şablon Çeviri Etiketleri

Django şablonları çeviri etiketlerine erişmek için {% load i18n %} kullanır:

{% trans %} ile basit dize çevirisi:

{% load i18n %}

<h1>{% trans "Welcome to our site" %}</h1>
<p>{% trans "This content will be translated." %}</p>

Değişken içeren dizeler için {% blocktrans %} ile blok çevirisi:

{% load i18n %}

{% blocktrans with username=user.username %}
    Hello, {{ username }}! You have new notifications.
{% endblocktrans %}

Çoğullama:

{% load i18n %}

{% blocktrans count counter=item_count %}
    You have {{ counter }} item in your cart.
{% plural %}
    You have {{ counter }} items in your cart.
{% endblocktrans %}

Dil bağlamını ayarlama:

{% load i18n %}

{% get_current_language as LANGUAGE_CODE %}
<html lang="{{ LANGUAGE_CODE }}">

URL Uluslararasılaştırması

Django'nun i18n_patterns işlevi URL kalıplarınızı etkin dil koduyla önekler:

# urls.py
from django.conf.urls.i18n import i18n_patterns
from django.urls import path, include

urlpatterns = [
    # Yerelleştirilmemiş URL'ler (yönetici, API vb.)
    path("api/", include("api.urls")),
]

urlpatterns += i18n_patterns(
    path("", include("pages.urls")),
    path("blog/", include("blog.urls")),
    path("accounts/", include("accounts.urls")),
    prefix_default_language=True,
)

Bu yapılandırmayla URL'leriniz şu hale gelir:

/en/blog/ — İngilizce blog
/es/blog/ — İspanyolca blog
/fr/blog/ — Fransızca blog

Django'nun yerleşik dil değiştirme görünümünü de eklemelisiniz:

from django.conf.urls.i18n import i18n_patterns
from django.urls import path, include

urlpatterns = [
    path("i18n/", include("django.conf.urls.i18n")),
]

urlpatterns += i18n_patterns(
    # ... kalıplarınız
)

Bu, kullanıcıların form POST aracılığıyla dil değiştirmesine olanak tanıyan {% url 'set_language' %} şablon etiketini etkinleştirir.

.po ve .mo Dosyalarıyla Çalışma

Django'nun çeviri sistemi GNU gettext'in dosya biçimine dayanır. Bu pipeline'ı otomatikleştirmeden önce anlamak şarttır.

gettext Django'da Nasıl Çalışır

İş akışı üç adımı izler:

Çıkarma — makemessages, Python dosyalarınızı ve şablonlarınızı çevrilebilir dizeler için tarar ve bunları .po (Taşınabilir Nesne) dosyalarına yazar.
Çevirme — Çevirmenler (veya AI), .po dosyalarındaki her msgid için msgstr alanını doldurur.
Derleme — compilemessages, .po dosyalarını Django'nun hızlı arama için çalışma zamanında okuduğu ikili .mo (Makine Nesnesi) dosyalarına dönüştürür.

Mesajları Çıkarma

Çıkarma komutunu proje kökünüzden çalıştırın:

# Tüm yapılandırılmış diller için mesajları çıkar
python manage.py makemessages --all --no-obsolete

# Belirli bir dil için çıkar
python manage.py makemessages -l es

# JavaScript dizelerini dahil et (Django'nun JS i18n kataloğu için)
python manage.py makemessages -d djangojs --all

--no-obsolete bayrağı, kodunuzda artık mevcut olmayan dizeler için girdileri kaldırarak .po dosyalarınızı temiz tutar.

.po Dosya Yapısı

Çıkarmadan sonra her yerel ayar bir .po dosyası alır:

locale/
├── es/
│   └── LC_MESSAGES/
│       └── django.po
├── fr/
│   └── LC_MESSAGES/
│       └── django.po
└── de/
    └── LC_MESSAGES/
        └── django.po

Bir .po dosya girdisi şöyle görünür:

#: templates/dashboard.html:5
msgid "Welcome to your dashboard"
msgstr ""

#: myapp/models.py:12
msgid "Article"
msgstr ""

#. Translators: This is a button label
#: templates/base.html:42
msgid "Submit"
msgstr ""

Her girdinin şunları içerir:

#: yorumları — kaynak dosya ve satır başvuruları
msgid — orijinal dize (kaynak dilinizde)
msgstr — çevrilmiş dize (çevirilene kadar boş)
#. yorumları — çevirmenler için notlar (kodunuzdaki Translators: yorumlarıyla eklenir)

Mesajları Derleme

Çeviriler tamamlandığında bunları derleyin:

python manage.py compilemessages

Bu, .po dosyalarının yanına .mo dosyaları oluşturur. Django bu ikili dosyaları başlangıçta hızlı çeviri aramaları için yükler. Yeni çevirileri derledikten sonra Django sunucunuzu (veya worker süreçlerinizi) yeniden başlatmanız gerekir.

Django'ya AI Destekli Çeviri Ekleme

.po dosyalarının manuel olarak çevrilmesi doğrudur ancak yavaştır. AI destekli çeviri, saniyeler içinde yüzlerce girdiyi işleyerek insan inceleyicilerin daha sonra geliştirebileceği çalışan bir ilk taslak sunar.

Python ile .po Dosyalarını Ayrıştırma ve Çevirme

polib kütüphanesi, .po dosyalarını programatik olarak okumak ve yazmak için temiz bir API sağlar:

pip install polib openai

İşte bir AI çeviri API'si kullanarak bir .po dosyasındaki çevrilmemiş girdileri çeviren bir komut dosyası:

# scripts/translate_po.py

import sys
import polib
from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY ortam değişkenini kullanır

TARGET_LANGUAGES = {
    "es": "Spanish",
    "fr": "French",
    "de": "German",
    "ja": "Japanese",
}


def translate_text(text: str, target_language: str) -> str:
    """Bir AI modeli kullanarak tek bir dize çevirir."""
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": (
                    f"You are a professional translator. Translate the following "
                    f"text to {target_language}. Preserve any Python format strings "
                    f"like %(name)s or {{variable}} exactly as they are. "
                    f"Return only the translated text, nothing else."
                ),
            },
            {"role": "user", "content": text},
        ],
        temperature=0.3,
    )
    return response.choices[0].message.content.strip()


def translate_po_file(po_path: str, lang_code: str) -> int:
    """Bir .po dosyasındaki tüm çevrilmemiş girdileri çevirir."""
    language_name = TARGET_LANGUAGES.get(lang_code)
    if not language_name:
        print(f"Desteklenmeyen dil kodu: {lang_code}")
        return 0

    po = polib.pofile(po_path)
    untranslated = po.untranslated_entries()

    if not untranslated:
        print(f"{po_path} dosyasında çevrilmemiş girdi yok")
        return 0

    print(f"{len(untranslated)} girdi {language_name} diline çevriliyor...")

    translated_count = 0
    for entry in untranslated:
        try:
            entry.msgstr = translate_text(entry.msgid, language_name)
            entry.flags.append("fuzzy")  # İnceleme gerektiğini işaretle
            translated_count += 1
        except Exception as e:
            print(f"  '{entry.msgid[:50]}...' çevrilirken hata: {e}")

    po.save()
    print(f"{po_path} dosyasında {translated_count} girdi çevrildi")
    return translated_count


if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("Kullanım: python translate_po.py <yol/django.po> <dil_kodu>")
        sys.exit(1)

    translate_po_file(sys.argv[1], sys.argv[2])

Çalıştırın:

python scripts/translate_po.py locale/es/LC_MESSAGES/django.po es
python scripts/translate_po.py locale/fr/LC_MESSAGES/django.po fr

Tüm Yerel Ayarlarda Toplu Çeviri

Daha büyük projeler için bir toplu komut dosyası her yerel ayarı aynı anda işler:

# scripts/translate_all.py

from pathlib import Path
from translate_po import translate_po_file, TARGET_LANGUAGES

LOCALE_DIR = Path("locale")


def translate_all_locales():
    """Tüm yapılandırılmış yerel ayarlar için çevrilmemiş girdileri çevirir."""
    total = 0
    for lang_code in TARGET_LANGUAGES:
        po_path = LOCALE_DIR / lang_code / "LC_MESSAGES" / "django.po"
        if po_path.exists():
            count = translate_po_file(str(po_path), lang_code)
            total += count
        else:
            print(f"{po_path} konumunda .po dosyası bulunamadı")

    print(f"\nToplam çeviri: {total}")


if __name__ == "__main__":
    translate_all_locales()

Kalite İnceleme İş Akışı

AI tarafından çevrilen girdiler, fuzzy bayrağıyla işaretlenir; bu Django'ya (ve insan inceleyicilere) çevirinin doğrulanması gerektiğini söyler. Bu kasıtlı ve önemlidir:

AI çevirir — tüm çevrilmemiş msgstr değerleri doldurulur ve fuzzy olarak işaretlenir
İnceleyiciler doğrular — anadil konuşanlar fuzzy girdileri kontrol eder ve onaylandıktan sonra bayrağı kaldırır
Derleme — varsayılan olarak yalnızca fuzzy olmayan girdiler derlenmiş .mo dosyalarına dahil edilir

Fuzzy girdileri incelemek için:

# Her yerel ayar için fuzzy girdi sayısını say
for lang in es fr de ja; do
    count=$(grep -c "^#, fuzzy" locale/$lang/LC_MESSAGES/django.po 2>/dev/null || echo 0)
    echo "$lang: $count fuzzy girdi"
done

İnceleme adımı için Poedit gibi .po dosya düzenleyicilerini veya web tabanlı platformları da kullanabilirsiniz.

Django Yerelleştirmesi için CI/CD Pipeline

CI/CD pipeline'ınızdaki çıkarma-çevirme-derleme döngüsünü otomatikleştirmek, çevirilerin kodunuzla senkronize kalmasını sağlar.

GitHub Actions İş Akışı

İşte main dalına her push'ta çalışan bir GitHub Actions iş akışı:

# .github/workflows/i18n.yml

name: i18n Translation Pipeline

on:
  push:
    branches: [main]
    paths:
      - "**.py"
      - "**.html"
      - "locale/**"

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install polib openai

      - name: Install gettext
        run: sudo apt-get install -y gettext

      - name: Extract messages
        run: python manage.py makemessages --all --no-obsolete

      - name: AI-translate new strings
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python scripts/translate_all.py

      - name: Compile messages
        run: python manage.py compilemessages

      - name: Commit translation updates
        run: |
          git config user.name "i18n-bot"
          git config user.email "i18n-bot@users.noreply.github.com"
          git add locale/
          git diff --staged --quiet || git commit -m "chore(i18n): update translations"
          git push

Pipeline Dökümü

Pipeline dört aşamayı izler:

Çıkarma — makemessages tüm Python dosyalarını ve şablonları yeni veya değiştirilmiş çevrilebilir dizeler için tarar
Çevirme — AI çeviri komut dosyası tüm çevrilmemiş girdileri doldurur ve fuzzy olarak işaretler
Derleme — compilemessages ikili .mo dosyalarını oluşturur
Commit — değişiklikler bir sonraki dağıtımda kullanılabilmeleri için depoya geri gönderilir

Üretim açısından kritik uygulamalar için, çevirme ve derleme adımları arasına manuel onay kapısı ekleyin. Bu, ekibinize fuzzy çevirileri yayınlanmadan önce incelemek için bir pencere sunar.

Yerel Geliştirme için Pre-commit Hook

Geliştirme sırasında eksik çevirileri yakalamak için bir pre-commit hook da ekleyebilirsiniz:

#!/bin/bash
# .git/hooks/pre-commit

# Çevrilmemiş dizeleri kontrol et
python manage.py makemessages --all --no-obsolete 2>/dev/null

if git diff --name-only locale/ | grep -q ".po$"; then
    echo "Uyarı: Yeni çevrilebilir dizeler tespit edildi."
    echo "Bunları çevirmek için 'python scripts/translate_all.py' çalıştırın."
fi

Better i18n Django ile Nasıl Entegre Olur

Yukarıdaki komut dosyaları çalışır ancak özel çeviri kodu yazmanızı, API anahtarlarını yönetmenizi, hız sınırlarını ele almanızı ve sıfırdan inceleme iş akışları oluşturmanızı gerektirir. Better i18n, tüm Django çeviri yaşam döngüsünü yöneten bir platform sunar.

Better i18n'in bir Django projesine nasıl uyduğu:

1. .po dosyalarını Better i18n ile senkronize edin

Özel ayrıştırma komut dosyaları yazmak yerine .po dosyalarınızı doğrudan Better i18n ile senkronize edebilirsiniz. Platform gettext biçimini yerel olarak okur ve her msgid/msgstr çiftini çeviri anahtarlarıyla eşler.

2. İnceleme iş akışıyla AI çevirisi

Better i18n, yazılım yerelleştirmesi için özel olarak ayarlanmış yerleşik AI çevirisi sağlar. Çeviriler, ekip üyelerinin önerileri onaylayabileceği, düzenleyebileceği veya reddedebileceği yönetilen bir inceleme iş akışından geçer — özel araç gerekmez.

3. Çevirileri yayınlayın ve çekin

Çeviriler onaylandıktan sonra bunları güncellenmiş .po dosyaları olarak Django projenize çekebilirsiniz. Yayınlama adımı, yalnızca incelenmiş çevirilerin kod tabanınıza ulaşmasını sağlar.

4. CI/CD entegrasyonu

Better i18n'in CLI'si, CI pipeline'ınızdaki özel komut dosyalarının yerini alabilir. Senkronize-çevir-çek döngüsü, GitHub Actions iş akışınızda tek bir komuta dönüşür.

Django'nun i18n özelliklerine daha ayrıntılı bir bakış için Django i18n çerçeve rehberimize bakın. İş akışınız için çeviri araçlarını değerlendiriyorsanız, AI çeviri araçları rehberimiz mevcut ortamı kapsamaktadır.

SSS

Django'da i18n ile l10n arasındaki fark nedir?

Uluslararasılaştırma (i18n), Django uygulamanızı çevrilebilir hale getirme sürecidir — dizeleri işaretlemek, ara yazılımı yapılandırmak, URL kalıplarını kurmak. Yerelleştirme (l10n) ise belirli bir dil ve bölge için gerçekten çeviriler sağlama ve yerel ayara özgü biçimlendirmeyi uyarlama sürecidir. Django'da USE_I18N = True çeviri çerçevesini etkinleştirirken USE_L10N = True tarihlerin, sayıların ve takvimlerin yerelleştirilmiş biçimlendirmesini etkinleştirir.

Django'da çoğullamayı nasıl ele alırım?

Django, Python kodunda ngettext() işlevi ve {% blocktrans count %} şablon etiketi aracılığıyla çoğullamayı ele alır. Gettext, karmaşık çoğul kuralları destekler — iki form (tekil/çoğul) olan İngilizce'nin aksine, Arapça gibi dillerin altı çoğul formu vardır ve Lehçe'nin üç formu vardır. Django'nun gettext entegrasyonu, tüm bunları .po dosyası başlığındaki çoğul form tanımları aracılığıyla ele alır.

Python örneği:

from django.utils.translation import ngettext

def item_count_message(count):
    return ngettext(
        "You have %(count)d item.",
        "You have %(count)d items.",
        count,
    ) % {"count": count}

Şablon örneği:

{% load i18n %}
{% blocktrans count counter=notifications %}
    You have {{ counter }} new notification.
{% plural %}
    You have {{ counter }} new notifications.
{% endblocktrans %}

Django .po dosyalarını çevirmek için AI kullanabilir miyim?

Evet. AI çeviri modelleri .po dosyalarını ayrıştırabilir ve msgstr girdilerini toplu olarak çevirebilir. Önerilen yaklaşım, .po dosyalarını programatik olarak okumak için polib gibi bir kütüphane kullanmak, çevrilmemiş dizeleri bir çeviri API'sine göndermek, sonuçları fuzzy bayrağıyla geri yazmak ve ardından çıktıyı anadil konuşanların incelemesine sunmaktır. Better i18n gibi araçlar, inceleme iş akışı dahil tüm bu pipeline'ı otomatikleştirir; böylece özel komut dosyaları korumanıza gerek kalmaz. Temel husus, AI çevirilerini her zaman üretime dağıtmadan önce insan incelemesi için işaretlemektir.

Django i18n ve AI ile Çeviri: Eksiksiz Kurulum Rehberi