Django i18n: Panduan Lengkap untuk Mengautomasikan Terjemahan Fail .po

Jika anda pernah melancarkan aplikasi Django dalam lebih daripada satu bahasa, anda tahu prosesnya. Anda membungkus rentetan anda dalam gettext(), menjalankan makemessages, membuka fail .po dengan beratus-ratus entri, dan mula menterjemah baris demi baris. Untuk dua bahasa dan lima puluh rentetan, ia masih boleh ditanggung. Untuk enam bahasa dan lima ratus rentetan, ia adalah satu hari kerja penuh yang tidak akan anda dapat kembali.

Panduan ini merangkumi saluran paip pengantarabangsaan (i18n) Django dari awal hingga akhir, menerangkan di mana ia menjadi masalah, dan menunjukkan cara mengautomasikan bahagian yang menyakitkan dengan terjemahan berkuasa AI.

Aliran Kerja Standard Django i18n

Sistem i18n terbina dalam Django direka dengan baik. Gelung utama kelihatan seperti ini:

Langkah 1: Tandakan rentetan untuk terjemahan dalam kod Python dan templat anda:

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>

Langkah 2: Ekstrak rentetan ke dalam fail .po:

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

Ini mengimbas keseluruhan kod sumber anda dan menghasilkan satu fail .po untuk setiap bahasa, yang mengandungi setiap rentetan yang boleh diterjemah:

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

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

Langkah 3: Terjemahkan setiap msgstr yang kosong secara manual.

Langkah 4: Kompil fail .po yang telah siap kepada fail binari .mo:

python manage.py compilemessages

Langkah 1, 2, dan 4 pantas. Langkah 3 adalah di mana proses menjadi gagal.

Mengapa Terjemahan Manual Tidak Berskala

Aplikasi Django biasa mempunyai antara 200 hingga 2,000 rentetan yang boleh diterjemah. Darabkan itu dengan bilangan bahasa sasaran, dan anda menghadapi komitmen masa yang serius.

Ini bukan aduan teori. Dalam thread Django Forum yang terkenal, seorang pembangun melaporkan menghabiskan 8+ jam setiap fail .po untuk terjemahan manual. Seorang penyumbang teras Django menggambarkan menghabiskan lebih 10 jam untuk menggabungkan terjemahan yang dihantar komuniti ke dalam satu keluaran, kebanyakannya untuk semakan, pembetulan format, dan pembaikan placeholder yang rosak.

Masalah ini bertambah dari masa ke masa:

• Placeholder rosak. Salin rentetan seperti Welcome, %(name)s! ke Google Translate, dan anda sering mendapat Willkommen, %(Name)s! atau Bienvenue, %(nom)s!. Kerosakan halus itu menyebabkan kerosakan masa jalan.
• Konsistensi hilang. Tanpa glosari, "dashboard" diterjemahkan sebagai "Instrumententafel" dalam satu fail dan "Dashboard" dalam fail lain. Tiga bulan kemudian, tiada siapa ingat yang mana satu yang disengajakan.
• Sprint menambah rentetan. Setiap feature branch menambah rentetan baru yang boleh diterjemah. Walaupun anda membayar untuk terjemahan penuh suku tahun lepas, anda kini mempunyai 40 entri yang belum diterjemah tersebar dalam fail .po anda.
• Pembantu AI membantu sekali. Anda boleh menampal fail .po ke dalam ChatGPT atau Claude dan mendapat keputusan yang baik. Tetapi sprint seterusnya, apabila 15 rentetan baru muncul, anda membuat prompt dari awal, menterjemah semula keseluruhan fail, dan berharap ia kekal konsisten dengan apa yang sudah ada.

Punca utama ialah terjemahan dianggap sebagai peristiwa sekali sahaja dan bukannya proses berperingkat dan boleh diulang.

Mengautomasikan Terjemahan dengan AI

Ideanya mudah: daripada manusia membuka setiap fail .po dan mengisi nilai msgstr, sebuah alat membaca fail, menghantar rentetan yang belum diterjemah kepada model AI atau API terjemahan, menulis keputusan kembali, dan memelihara segala yang lain (komen, struktur fail, placeholder, bentuk jamak).

TranslateBot Django ialah pakej sumber terbuka yang melakukan tepat ini. Ia disambungkan ke dalam sistem arahan pengurusan Django, jadi ia sesuai dengan aliran kerja yang anda sudah ada.

Persediaan Langkah demi Langkah

1. Pasang Pakej

pip install translatebot-django

Atau, jika anda menggunakan uv (disyorkan):

uv add --dev translatebot-django

Memasang sebagai kebergantungan pembangunan adalah disengajakan. Anda hanya memerlukan TranslateBot semasa menghasilkan terjemahan, bukan pada masa jalan dalam pengeluaran.

2. Tambah ke INSTALLED_APPS

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

3. Konfigurasikan Penyedia AI Anda

# settings.py
import os

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

TranslateBot menggunakan LiteLLM di bawah, yang bermaksud anda boleh menukar mana-mana model daripada 100+ dengan menukar satu rentetan:

Untuk DeepL, pasang tambahan: pip install translatebot-django[deepl]. Tier percuma DeepL memberikan anda 500,000 aksara sebulan tanpa kos, yang mencukupi untuk kebanyakan projek kecil hingga sederhana.

4. Tentukan Bahasa Anda

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

5. Jalankan Terjemahan

python manage.py translate

Itu sahaja. TranslateBot mengimbas projek anda untuk fail .po, mengenal pasti entri yang belum diterjemah, menghantarnya kepada model AI yang dikonfigurasikan dalam kelompok yang dioptimumkan, dan menulis keputusan kembali. Terjemahan yang sedia ada tidak disentuh.

Untuk menterjemah satu bahasa:

python manage.py translate --target-lang nl

Output kelihatan seperti ini:

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

6. Kompil Seperti Biasa

python manage.py compilemessages

Aliran kerja penuh anda sekarang ialah:

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

Tiga arahan. Setiap bahasa. Setiap sprint.

Berperingkat Secara Reka Bentuk

Ciri paling penting untuk aliran kerja yang boleh diulang ialah terjemahan berperingkat. TranslateBot hanya menterjemah entri di mana msgstr kosong. Jika anda mempunyai 500 rentetan dan 15 adalah baru sprint ini, hanya 15 itu yang dihantar ke API.

Ini penting untuk sebab praktikal:

1. Kos. Anda hanya membayar untuk rentetan baru, bukan keseluruhan fail.
2. Kelajuan. Menterjemah 15 rentetan mengambil saat, bukan minit.
3. Kestabilan. Terjemahan yang anda sudah semak dan luluskan tidak pernah ditimpa (melainkan anda secara eksplisit menggunakan --overwrite).

Keselamatan Placeholder

Django menggunakan beberapa format placeholder: %(name)s, %s, %d, {0}, {name}, dan tag HTML sebaris seperti <strong> atau <a href="...">. Jika mana-mana daripadanya rosak dalam terjemahan, anda mendapat ralat masa jalan atau penanda rosak.

TranslateBot mengarahkan model AI untuk memelihara semua format placeholder dan mengesahkan output. Rentetan seperti:

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

Diterjemah ke bahasa Belanda sebagai:

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

Setiap placeholder kekal utuh.

Mengawal Kualiti dengan TRANSLATING.md

Model AI menterjemah lebih baik apabila memahami konteks. TranslateBot mencari fail TRANSLATING.md di root projek anda dan menyertakan kandungannya dalam setiap permintaan terjemahan.

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

Fail ini dikawal versi bersama kod anda, jadi seluruh pasukan anda berkongsi konteks terjemahan yang sama. Anda juga boleh meletakkan fail TRANSLATING.md untuk setiap aplikasi yang mempunyai terminologi khusus. Modul rekod perubatan dan modul pengebilan boleh mempunyai glosari masing-masing.

Pratonton Sebelum Commit

Bendera --dry-run menunjukkan dengan tepat apa yang akan diterjemah tanpa membuat sebarang panggilan API atau mengubah suai fail:

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

Ini berguna sebelum terjemahan besar atau apabila memperkenalkan ahli pasukan baru yang ingin memahami apa yang dilakukan arahan sebelum berkomitmen kepada kos API.

Integrasi CI/CD

Terjemahan menjadi lapuk tidak dapat dielakkan tanpa penguatkuasaan. TranslateBot menyertakan arahan pengurusan check_translations yang direka untuk saluran paip CI:

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

Bendera --makemessages menjalankan makemessages -a --no-obsolete dahulu, memastikan fail .po mencerminkan kod sumber semasa sebelum memeriksa. Jika mana-mana entri belum diterjemah atau kabur, arahan keluar dengan kod 1 dan gagalkan pembinaan:

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

Aliran kerja pembangun biasa menjadi:

1. Tambah rentetan baru yang boleh diterjemah dalam feature branch.
2. CI gagal kerana rentetan tersebut belum diterjemah.
3. Jalankan python manage.py translate secara tempatan.
4. Commit fail .po yang dikemas kini.
5. CI lulus.

Terjemahan tidak pernah diam-diam menjadi tidak segerak.

Menterjemah Kandungan Pangkalan Data

Jika aplikasi anda menyimpan kandungan yang boleh diterjemah dalam pangkalan data (nama produk, tajuk catatan blog, label kategori), TranslateBot juga berintegrasi dengan django-modeltranslation:

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

Logik berperingkat yang sama digunakan: hanya medan di mana nilai bahasa sasaran kosong yang akan diterjemah.

Perbandingan Kos

Salah satu soalan yang paling kerap ditanya ialah sama ada terjemahan AI menjimatkan kos berbanding alternatif. Berikut ialah perbandingan kasar untuk projek dengan 500 rentetan yang boleh diterjemah merentasi 5 bahasa:

Angka berubah bergantung kepada bilangan rentetan dan bahasa sasaran, tetapi perbezaan peringkat magnitud adalah konsisten. Untuk penyelenggaraan berterusan (menterjemah 20-50 rentetan baru yang ditambah setiap sprint), kos AI pada dasarnya sifar.

Amalan Terbaik

Mulakan dengan --dry-run. Sebelum terjemahan sebenar yang pertama, pratonton apa yang akan berlaku. Ini membina keyakinan dan menangkap isu konfigurasi awal.

Commit fail .po sebelum menterjemah. Jika ada yang tidak kena, git checkout membawa anda kembali ke keadaan bersih serta-merta.

Tulis TRANSLATING.md dari hari pertama. Walaupun fail ringkas dengan penerangan projek dan beberapa peraturan terminologi secara ketara meningkatkan kualiti terjemahan.

Tambah check_translations ke CI. Langkah tunggal ini menghalang mod kegagalan i18n yang paling biasa: rentetan yang ditanda untuk terjemahan tetapi tidak pernah benar-benar diterjemah.

Gunakan gpt-4o-mini atau DeepL untuk kecekapan kos. Simpan model premium seperti GPT-4o atau Claude untuk projek di mana ketepatan penting, seperti salinan pemasaran, teks undang-undang, atau terminologi khusus domain.

Semak rentetan kritikal. Terjemahan AI cukup baik untuk kebanyakan teks UI, tetapi minta penutur asli menyemak apa-apa yang mengikat secara sah, kritikal keselamatan, atau berhadapan pelanggan dalam konteks berisiko tinggi.

Dari Jam ke Saat

Rangka kerja i18n Django cemerlang dalam mengekstrak dan mengkompil terjemahan. Jurang sentiasa berada pada langkah terjemahan itu sendiri, kerja membosankan dan mudah ralat mengisi beratus-ratus nilai msgstr merentasi pelbagai bahasa.

TranslateBot menutup jurang itu. Pasang, halakan ke penyedia AI, dan jalankan satu arahan. Rentetan baru diterjemah. Rentetan sedia ada tidak disentuh. Placeholder kekal utuh. CI menangkap apa sahaja yang terlepas.

Fail .po anda berhenti menjadi beban dan mula menjadi sekadar sebahagian daripada pembinaan.

pip install translatebot-django

Mulakan di translatebot.dev.