Django i18n: Ang Kumpletong Gabay sa Pag-automate ng .po File Translation

Kung nakapag-deploy ka na ng Django app sa higit sa isang wika, alam mo na ang proseso. Ibinabalot mo ang iyong mga string sa gettext(), pinapatakbo ang makemessages, binubuksan ang .po file na may daan-daang entry, at sinisimulan ang pagsasalin nang linya-linya. Para sa dalawang wika at limampung string, kaya pa. Para sa anim na wika at limang daang string, isang buong araw ng trabaho na hindi mo na mababawi.

Sinasaklaw ng gabay na ito ang internationalization (i18n) pipeline ng Django mula simula hanggang dulo, ipinapaliwanag kung saan ito nasisira, at ipinapakita kung paano i-automate ang pinakamahirap na bahagi gamit ang AI-powered na pagsasalin.

Ang Karaniwang Django i18n Workflow

Ang built-in na i18n system ng Django ay mahusay na dinisenyo. Ganito ang pangunahing loop:

Hakbang 1: Markahan ang mga string para sa pagsasalin sa iyong Python code at mga template:

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>

Hakbang 2: I-extract ang mga string sa .po file:

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

Ini-scan nito ang buong codebase at gumagawa ng isang .po file bawat wika, na naglalaman ng bawat maisasaling string:

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

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

Hakbang 3: Isalin ang bawat walang laman na msgstr nang mano-mano.

Hakbang 4: I-compile ang tapos na .po file sa binary na .mo file:

python manage.py compilemessages

Mabilis ang Hakbang 1, 2, at 4. Sa Hakbang 3 nasira ang proseso.

Bakit Hindi Nag-i-scale ang Manual na Pagsasalin

Ang karaniwang Django application ay may humigit-kumulang 200 hanggang 2,000 na maisasaling string. I-multiply mo iyon sa bilang ng target na wika, at makikita mo ang seryosong commitment sa oras.

Hindi ito theoretical na reklamo. Sa isang kilalang Django Forum thread, nag-ulat ang isang developer na gumastos ng 8+ oras bawat .po file sa manual na pagsasalin. Isang Django core contributor ang naglalarawan na gumastos ng mahigit 10 oras para isama ang community-submitted na mga salin sa isang release, karamihan sa review, formatting correction, at pag-aayos ng sirang mga placeholder.

Lumalalala ang mga problema sa paglipas ng panahon:

• Nasisira ang mga placeholder. I-copy ang string tulad ng Welcome, %(name)s! sa Google Translate, at madalas na babalik ang Willkommen, %(Name)s! o Bienvenue, %(nom)s!. Ang banayad na corruption na iyon ay nagdudulot ng runtime crash.
• Nawawala ang consistency. Kung walang glossary, ang "dashboard" ay isinalin bilang "Instrumententafel" sa isang file at "Dashboard" sa isa pa. Tatlong buwan pagkatapos, walang nakaka-alaala kung alin ang intensyonal.
• Nagdadagdag ang mga sprint ng string. Bawat feature branch ay nagdadagdag ng bagong maisasaling string. Kahit nagbayad ka ng buong translation pass noong nakaraang quarter, mayroon ka nang 40 na hindi naisaling entry na nakakalat sa iyong mga .po file.
• Isang beses lang nakakatulong ang mga AI assistant. Pwede mong i-paste ang .po file sa ChatGPT o Claude at makakuha ng maayos na resulta. Pero sa susunod na sprint, kapag may lumabas na 15 bagong string, nagpo-prompt ka ulit mula sa simula, muling isinasalin ang buong file, at umaasang magiging consistent ito sa dati nang nandoon.

Ang pangunahing dahilan ay ang pagsasalin ay itinuturing bilang isang one-time na pangyayari sa halip na isang incremental at paulit-ulit na proseso.

Pag-automate ng Pagsasalin gamit ang AI

Diretso ang ideya: sa halip na isang tao ang magbubukas ng bawat .po file at magpupuno ng mga msgstr value, isang tool ang nagbabasa ng file, nagpapadala ng mga hindi naisaling string sa isang AI model o translation API, isinusulat ang mga resulta pabalik, at pinapanatili ang lahat ng iba pa (mga komento, file structure, placeholder, plural form).

TranslateBot Django ay isang open-source na package na eksaktong ginagawa ito. Naka-plug ito sa management command system ng Django, kaya tumutugma sa workflow na mayroon ka na.

Hakbang-hakbang na Setup

1. I-install ang Package

pip install translatebot-django

O, kung gumagamit ka ng uv (inirerekomenda):

uv add --dev translatebot-django

Intensyonal ang pag-install bilang dev dependency. Kailangan mo lang ang TranslateBot kapag gumagawa ng mga pagsasalin, hindi sa runtime sa production.

2. Idagdag sa INSTALLED_APPS

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

3. I-configure ang Iyong AI Provider

# settings.py
import os

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

Ginagamit ng TranslateBot ang LiteLLM sa ilalim, na nangangahulugang pwede mong palitan ang kahit alin sa 100+ na model sa pamamagitan ng pagbabago ng isang string:

Para sa DeepL, i-install ang extra: pip install translatebot-django[deepl]. Ang libreng tier ng DeepL ay nagbibigay sa iyo ng 500,000 character bawat buwan nang walang bayad, na sapat para sa karamihan ng maliliit hanggang katamtamang proyekto.

4. Tukuyin ang Iyong mga Wika

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

5. Patakbuhin ang Pagsasalin

python manage.py translate

Iyon lang. Ini-scan ng TranslateBot ang iyong proyekto para sa mga .po file, tinutukoy ang mga hindi naisaling entry, ipinapadala ang mga ito sa naka-configure na AI model sa optimized na batch, at isinusulat ang mga resulta. Ang mga umiiral na pagsasalin ay hindi ginagalaw.

Para magsalin ng isang wika:

python manage.py translate --target-lang nl

Ganito ang output:

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

6. I-compile Gaya ng Dati

python manage.py compilemessages

Ang buong workflow mo ngayon ay:

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

Tatlong command. Bawat wika. Bawat sprint.

Incremental sa Disenyo

Ang pinakamahalagang feature para sa isang paulit-ulit na workflow ay ang incremental na pagsasalin. Isinalin lang ng TranslateBot ang mga entry kung saan walang laman ang msgstr. Kung mayroon kang 500 string at 15 ang bago ngayong sprint, ang 15 na iyon lang ang ipapadala sa API.

Mahalaga ito para sa mga praktikal na dahilan:

1. Gastos. Nagbabayad ka lang para sa mga bagong string, hindi sa buong file.
2. Bilis. Ang pagsasalin ng 15 string ay tumatagal ng segundo, hindi minuto.
3. Katatagan. Ang mga pagsasalin na na-review at na-approve mo na ay hindi kailanman i-overwrite (maliban kung tahasan mong ilagay ang --overwrite).

Kaligtasan ng Placeholder

Gumagamit ang Django ng ilang placeholder format: %(name)s, %s, %d, {0}, {name}, at inline HTML tag tulad ng <strong> o <a href="...">. Kung alinman sa mga ito ang nasira sa pagsasalin, makakakuha ka ng runtime error o sirang markup.

Itinuturo ng TranslateBot sa AI model na panatilihin ang lahat ng placeholder format at bina-validate ang output. Ang string na tulad nito:

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

Naisalin sa Dutch bilang:

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

Bawat placeholder ay nananatiling buo.

Pagkontrol ng Kalidad gamit ang TRANSLATING.md

Mas magaling magsalin ang mga AI model kapag naiintindihan nila ang konteksto. Hinahanap ng TranslateBot ang TRANSLATING.md file sa root ng iyong proyekto at isinasama ang mga nilalaman nito sa bawat translation request.

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

Ang file na ito ay version-controlled kasama ng iyong code, kaya ang buong team mo ay nagbabahagi ng parehong translation context. Pwede ka ring maglagay ng per-app na TRANSLATING.md file para sa mga app na may specialized na terminolohiya. Ang medical records module at billing module ay pwedeng magkaroon ng kanya-kanyang glossary.

Preview Bago Mag-commit

Ipinapakita ng --dry-run flag kung ano eksaktong isasalin nang walang ginagawang API call o binabago ang mga file:

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

Kapaki-pakinabang ito bago ang isang malaking translation run o kapag ino-onboard ang bagong team member na gustong maunawaan kung ano ang ginagawa ng command bago mag-commit sa mga gastos sa API.

CI/CD Integration

Hindi maiiwasan ang pagiging luma ng mga pagsasalin kung walang pagpapatupad. Kasama sa TranslateBot ang check_translations management command na dinisenyo para sa mga CI pipeline:

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

Ang --makemessages flag ay nagpapatakbo muna ng makemessages -a --no-obsolete, na tinitiyak na ang mga .po file ay nagpapakita ng kasalukuyang source code bago mag-check. Kung may mga entry na hindi naisalin o fuzzy, lalabas ang command na may code 1 at mafe-fail ang build:

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

Ang karaniwang developer workflow ay nagiging:

1. Magdagdag ng bagong maisasaling string sa feature branch.
2. Mag-fail ang CI dahil hindi naisalin ang mga string na iyon.
3. Patakbuhin ang python manage.py translate nang lokal.
4. I-commit ang na-update na mga .po file.
5. Pumasa ang CI.

Hindi kailanman tahimik na mawawala sa sync ang mga pagsasalin.

Pagsasalin ng Database Content

Kung ang iyong application ay nag-iimbak ng maisasaling content sa database (mga pangalan ng produkto, mga pamagat ng blog post, mga label ng kategorya), ang TranslateBot ay nag-i-integrate din sa 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

Ang parehong incremental na logic ang nag-a-apply: ang mga field lang kung saan walang laman ang target language value ang maisasalin.

Paghahambing ng Gastos

Isa sa mga pinakamadalas na tanong ay kung ang AI translation ay cost-effective kumpara sa mga alternatibo. Narito ang isang rough na paghahambing para sa isang proyekto na may 500 maisasaling string sa 5 wika:

Nagbabago ang mga numero depende sa bilang ng string at target na wika, pero consistent ang pagkakaiba sa order-of-magnitude. Para sa patuloy na maintenance (pagsasalin ng 20-50 bagong string na idinadagdag bawat sprint), halos zero ang gastos sa AI.

Pinakamahuhusay na Kasanayan

Magsimula sa --dry-run. Bago ang iyong unang tunay na translation run, i-preview kung ano ang mangyayari. Nagtatayo ito ng kumpiyansa at nakakahuli ng mga isyu sa configuration nang maaga.

I-commit ang mga .po file bago magsalin. Kung may mali, agad kang maibabalik sa malinis na estado ng git checkout.

Sumulat ng TRANSLATING.md mula sa unang araw. Kahit isang maikling file na may paglalarawan ng iyong proyekto at ilang panuntunan sa terminolohiya ay mapapansing nagpapabuti ng kalidad ng pagsasalin.

Idagdag ang check_translations sa CI. Ang isang hakbang na ito ang pumipigil sa pinakakaraniwang i18n failure mode: mga string na minarkahan para sa pagsasalin pero hindi talaga naisalin.

Gamitin ang gpt-4o-mini o DeepL para sa cost efficiency. I-save ang mga premium model tulad ng GPT-4o o Claude para sa mga proyektong mahalaga ang katumpakan, tulad ng marketing copy, legal text, o domain-specific na terminolohiya.

I-review ang mga kritikal na string. Sapat na ang mga AI translation para sa karamihan ng UI text, pero magpa-review sa isang native speaker ng anumang bagay na legal na nagbubuklod, kritikal sa kaligtasan, o nakaharap sa customer sa isang high-stakes na konteksto.

Mula Oras Hanggang Segundo

Mahusay ang i18n framework ng Django sa pag-extract at pag-compile ng mga pagsasalin. Ang gap ay palaging nasa translation step mismo, ang nakakapagod at madaling magkamaling trabaho ng pagpuno ng daan-daang msgstr value sa maraming wika.

Isinasara ng TranslateBot ang gap na iyon. I-install ito, ituro sa isang AI provider, at magpatakbo ng isang command. Ang mga bagong string ay naisasalin. Ang mga umiiral na string ay hindi ginagalaw. Ang mga placeholder ay nananatiling buo. Nahuhueli ng CI ang anumang makakalusot.

Ang iyong mga .po file ay tumitigil na maging isang pabigat at nagiging isa na lamang bahagi ng build.

pip install translatebot-django

Magsimula sa translatebot.dev.