Django i18n: Ο Πλήρης Οδηγός για Αυτοματοποίηση Μετάφρασης Αρχείων .po

Αν έχετε ποτέ κυκλοφορήσει μια εφαρμογή Django σε περισσότερες από μία γλώσσες, γνωρίζετε τη διαδικασία. Τυλίγετε τα string σας σε gettext(), τρέχετε makemessages, ανοίγετε ένα αρχείο .po με εκατοντάδες εγγραφές και αρχίζετε να μεταφράζετε γραμμή προς γραμμή. Για δύο γλώσσες και πενήντα string, είναι ανεκτό. Για έξι γλώσσες και πεντακόσια string, είναι μια ολόκληρη εργάσιμη μέρα που δεν θα πάρετε ποτέ πίσω.

Αυτός ο οδηγός καλύπτει τη διαδικασία διεθνοποίησης (i18n) του Django από την αρχή μέχρι το τέλος, εξηγεί πού αποτυγχάνει και δείχνει πώς να αυτοματοποιήσετε το επώδυνο μέρος με μετάφραση που βασίζεται σε AI.

Η τυπική ροή εργασίας Django i18n

Το ενσωματωμένο σύστημα i18n του Django είναι καλά σχεδιασμένο. Ο κύριος βρόχος μοιάζει κάπως έτσι:

Βήμα 1: Σημειώστε τα string για μετάφραση στον κώδικα Python και τα 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>

Βήμα 2: Εξαγάγετε τα string σε αρχεία .po:

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

Αυτό σαρώνει ολόκληρη τη βάση κώδικα και δημιουργεί ένα αρχείο .po ανά γλώσσα, που περιέχει κάθε μεταφράσιμο string:

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

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

Βήμα 3: Μεταφράστε κάθε κενό msgstr με το χέρι.

Βήμα 4: Μεταγλωττίστε τα ολοκληρωμένα αρχεία .po σε δυαδικά αρχεία .mo:

python manage.py compilemessages

Τα βήματα 1, 2 και 4 είναι γρήγορα. Το βήμα 3 είναι εκεί που η διαδικασία καταρρέει.

Γιατί η χειροκίνητη μετάφραση δεν κλιμακώνεται

Μια τυπική εφαρμογή Django έχει κάπου μεταξύ 200 και 2.000 μεταφράσιμα string. Πολλαπλασιάστε αυτό με τον αριθμό των γλωσσών-στόχων και βλέπετε μια σοβαρή δέσμευση χρόνου.

Αυτό δεν είναι θεωρητικό παράπονο. Σε ένα γνωστό νήμα του Django Forum, ένας προγραμματιστής ανέφερε ότι ξοδεύει 8+ ώρες ανά αρχείο .po κάνοντας χειροκίνητες μεταφράσεις. Ένας βασικός συνεισφέρων του Django περιέγραψε ότι ξόδεψε πάνω από 10 ώρες για να ενσωματώσει μεταφράσεις που υπέβαλε η κοινότητα σε μια μόνο έκδοση, κυρίως σε αναθεώρηση, διορθώσεις μορφοποίησης και επιδιόρθωση κατεστραμμένων placeholder.

Τα προβλήματα συσσωρεύονται με τον χρόνο:

• Τα placeholder χαλάνε. Αντιγράψτε ένα string όπως Welcome, %(name)s! στο Google Translate και συχνά θα πάρετε πίσω Willkommen, %(Name)s! ή Bienvenue, %(nom)s!. Αυτή η λεπτή αλλοίωση προκαλεί σφάλματα κατά την εκτέλεση.
• Η συνέπεια χάνεται. Χωρίς γλωσσάρι, το "dashboard" μεταφράζεται ως "Instrumententafel" σε ένα αρχείο και "Dashboard" σε άλλο. Τρεις μήνες αργότερα, κανείς δεν θυμάται ποιο ήταν σκόπιμο.
• Τα sprint προσθέτουν string. Κάθε feature branch προσθέτει νέα μεταφράσιμα string. Ακόμα κι αν πληρώσατε για πλήρη μετάφραση το προηγούμενο τρίμηνο, τώρα έχετε 40 αμετάφραστες εγγραφές διάσπαρτες στα αρχεία .po.
• Οι βοηθοί AI βοηθούν μία φορά. Μπορείτε να επικολλήσετε ένα αρχείο .po στο ChatGPT ή το Claude και να πάρετε αξιοπρεπή αποτελέσματα. Αλλά στο επόμενο sprint, όταν εμφανιστούν 15 νέα string, κάνετε prompt από την αρχή, ξαναμεταφράζετε ολόκληρο το αρχείο και ελπίζετε να παραμείνει συνεπές με αυτό που ήταν ήδη εκεί.

Η βασική αιτία είναι ότι η μετάφραση αντιμετωπίζεται ως μεμονωμένο γεγονός αντί για μια σταδιακή, επαναλαμβανόμενη διαδικασία.

Αυτοματοποίηση μετάφρασης με AI

Η ιδέα είναι απλή: αντί ένας άνθρωπος να ανοίγει κάθε αρχείο .po και να συμπληρώνει τιμές msgstr, ένα εργαλείο διαβάζει το αρχείο, στέλνει τα αμετάφραστα string σε ένα μοντέλο AI ή API μετάφρασης, γράφει τα αποτελέσματα πίσω και διατηρεί όλα τα υπόλοιπα (σχόλια, δομή αρχείου, placeholder, μορφές πληθυντικού).

Το TranslateBot Django είναι ένα πακέτο ανοιχτού κώδικα που κάνει ακριβώς αυτό. Συνδέεται στο σύστημα εντολών διαχείρισης του Django, οπότε ταιριάζει στη ροή εργασίας που ήδη έχετε.

Εγκατάσταση βήμα προς βήμα

1. Εγκαταστήστε το πακέτο

pip install translatebot-django

Ή, αν χρησιμοποιείτε uv (συνιστάται):

uv add --dev translatebot-django

Η εγκατάσταση ως εξάρτηση ανάπτυξης είναι σκόπιμη. Χρειάζεστε το TranslateBot μόνο κατά τη δημιουργία μεταφράσεων, όχι κατά την εκτέλεση σε παραγωγή.

2. Προσθέστε στο INSTALLED_APPS

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

3. Ρυθμίστε τον πάροχο AI

# settings.py
import os

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

Το TranslateBot χρησιμοποιεί το LiteLLM εσωτερικά, που σημαίνει ότι μπορείτε να αλλάξετε οποιοδήποτε από τα 100+ μοντέλα αλλάζοντας ένα μόνο string:

Για το DeepL, εγκαταστήστε το επιπλέον: pip install translatebot-django[deepl]. Το δωρεάν επίπεδο του DeepL σας δίνει 500.000 χαρακτήρες τον μήνα χωρίς κόστος, που είναι αρκετό για τα περισσότερα μικρά έως μεσαία έργα.

4. Ορίστε τις γλώσσες σας

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

5. Εκτελέστε τη μετάφραση

python manage.py translate

Αυτό ήταν. Το TranslateBot σαρώνει το έργο σας για αρχεία .po, εντοπίζει αμετάφραστες εγγραφές, τις στέλνει στο ρυθμισμένο μοντέλο AI σε βελτιστοποιημένες παρτίδες και γράφει τα αποτελέσματα. Οι υπάρχουσες μεταφράσεις δεν πειράζονται.

Για μετάφραση μίας μόνο γλώσσας:

python manage.py translate --target-lang nl

Η έξοδος μοιάζει κάπως έτσι:

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

6. Μεταγλωττίστε ως συνήθως

python manage.py compilemessages

Η πλήρης ροή εργασίας σας τώρα είναι:

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

Τρεις εντολές. Κάθε γλώσσα. Κάθε sprint.

Σταδιακή εκ σχεδιασμού

Το πιο σημαντικό χαρακτηριστικό για μια επαναλαμβανόμενη ροή εργασίας είναι η σταδιακή μετάφραση. Το TranslateBot μεταφράζει μόνο εγγραφές όπου το msgstr είναι κενό. Αν έχετε 500 string και 15 είναι νέα σε αυτό το sprint, μόνο αυτά τα 15 αποστέλλονται στο API.

Αυτό έχει σημασία για πρακτικούς λόγους:

1. Κόστος. Πληρώνετε μόνο για νέα string, όχι ολόκληρο το αρχείο.
2. Ταχύτητα. Η μετάφραση 15 string παίρνει δευτερόλεπτα, όχι λεπτά.
3. Σταθερότητα. Μεταφράσεις που έχετε ήδη αναθεωρήσει και εγκρίνει δεν αντικαθίστανται ποτέ (εκτός αν περάσετε ρητά --overwrite).

Ασφάλεια placeholder

Το Django χρησιμοποιεί διάφορες μορφές placeholder: %(name)s, %s, %d, {0}, {name} και ενσωματωμένα HTML tag όπως <strong> ή <a href="...">. Αν οποιοδήποτε από αυτά αλλοιωθεί στη μετάφραση, λαμβάνετε σφάλματα κατά την εκτέλεση ή κατεστραμμένο markup.

Το TranslateBot δίνει οδηγίες στο μοντέλο AI να διατηρήσει όλες τις μορφές placeholder και επικυρώνει την έξοδο. Ένα string όπως:

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

Μεταφράζεται στα ολλανδικά ως:

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

Κάθε placeholder επιβιώνει ανέπαφο.

Έλεγχος ποιότητας με TRANSLATING.md

Τα μοντέλα AI μεταφράζουν καλύτερα όταν κατανοούν το πλαίσιο. Το TranslateBot αναζητά ένα αρχείο TRANSLATING.md στη ρίζα του έργου σας και περιλαμβάνει τα περιεχόμενά του σε κάθε αίτημα μετάφρασης.

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

Αυτό το αρχείο ελέγχεται κατά την έκδοση μαζί με τον κώδικά σας, οπότε ολόκληρη η ομάδα μοιράζεται το ίδιο πλαίσιο μετάφρασης. Μπορείτε επίσης να τοποθετήσετε αρχεία TRANSLATING.md ανά εφαρμογή για εφαρμογές με εξειδικευμένη ορολογία. Ένα module ιατρικών αρχείων και ένα module τιμολόγησης μπορούν να έχουν το καθένα το δικό του γλωσσάρι.

Προεπισκόπηση πριν το commit

Η σημαία --dry-run δείχνει ακριβώς τι θα μεταφραστεί χωρίς να κάνει κλήσεις API ή να τροποποιεί αρχεία:

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

Αυτό είναι χρήσιμο πριν από μια μεγάλη εκτέλεση μετάφρασης ή κατά την ένταξη ενός νέου μέλους ομάδας που θέλει να καταλάβει τι κάνει η εντολή πριν δεσμευτεί στα κόστη API.

Ενσωμάτωση CI/CD

Η απαρχαίωση μεταφράσεων είναι αναπόφευκτη χωρίς επιβολή. Το TranslateBot περιλαμβάνει μια εντολή διαχείρισης check_translations σχεδιασμένη για pipelines 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

Η σημαία --makemessages τρέχει πρώτα makemessages -a --no-obsolete, εξασφαλίζοντας ότι τα αρχεία .po αντικατοπτρίζουν τον τρέχοντα πηγαίο κώδικα πριν τον έλεγχο. Αν υπάρχουν αμετάφραστες ή ασαφείς εγγραφές, η εντολή τερματίζει με κωδικό 1 και αποτυγχάνει το 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

Η τυπική ροή εργασίας του προγραμματιστή γίνεται:

1. Προσθέστε νέα μεταφράσιμα string σε ένα feature branch.
2. Το CI αποτυγχάνει επειδή αυτά τα string είναι αμετάφραστα.
3. Τρέξτε python manage.py translate τοπικά.
4. Κάντε commit τα ενημερωμένα αρχεία .po.
5. Το CI περνάει.

Οι μεταφράσεις δεν αποσυγχρονίζονται ποτέ σιωπηλά.

Μετάφραση περιεχομένου βάσης δεδομένων

Αν η εφαρμογή σας αποθηκεύει μεταφράσιμο περιεχόμενο στη βάση δεδομένων (ονόματα προϊόντων, τίτλους αναρτήσεων blog, ετικέτες κατηγοριών), το TranslateBot ενσωματώνεται επίσης με το 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

Η ίδια σταδιακή λογική ισχύει: μόνο πεδία όπου η τιμή της γλώσσας-στόχου είναι κενή μεταφράζονται.

Σύγκριση κόστους

Μία από τις πιο συχνές ερωτήσεις είναι αν η μετάφραση AI είναι οικονομικά αποδοτική σε σύγκριση με τις εναλλακτικές. Ακολουθεί μια κατά προσέγγιση σύγκριση για ένα έργο με 500 μεταφράσιμα string σε 5 γλώσσες:

Οι αριθμοί αλλάζουν ανάλογα με τον αριθμό string και τις γλώσσες-στόχους, αλλά η διαφορά τάξης μεγέθους είναι σταθερή. Για συνεχή συντήρηση (μετάφραση των 20-50 νέων string που προστίθενται σε κάθε sprint), το κόστος AI είναι ουσιαστικά μηδέν.

Βέλτιστες πρακτικές

Ξεκινήστε με --dry-run. Πριν την πρώτη πραγματική εκτέλεση μετάφρασης, δείτε τι θα συμβεί. Αυτό χτίζει εμπιστοσύνη και εντοπίζει ζητήματα διαμόρφωσης νωρίς.

Κάντε commit τα αρχεία .po πριν τη μετάφραση. Αν κάτι πάει στραβά, git checkout σας επαναφέρει αμέσως σε καθαρή κατάσταση.

Γράψτε ένα TRANSLATING.md από την πρώτη μέρα. Ακόμα και ένα σύντομο αρχείο με την περιγραφή του έργου και μερικούς κανόνες ορολογίας βελτιώνει μετρήσιμα την ποιότητα μετάφρασης.

Προσθέστε check_translations στο CI. Αυτό το μεμονωμένο βήμα αποτρέπει τον πιο συνηθισμένο τρόπο αποτυχίας i18n: string που σημειώθηκαν για μετάφραση αλλά δεν μεταφράστηκαν ποτέ πραγματικά.

Χρησιμοποιήστε gpt-4o-mini ή DeepL για οικονομική αποδοτικότητα. Κρατήστε τα premium μοντέλα όπως GPT-4o ή Claude για έργα όπου η ακρίβεια έχει σημασία, όπως κείμενο μάρκετινγκ, νομικό κείμενο ή εξειδικευμένη ορολογία τομέα.

Ελέγξτε τα κρίσιμα string. Οι μεταφράσεις AI είναι αρκετά καλές για το περισσότερο κείμενο UI, αλλά ζητήστε από φυσικό ομιλητή να ελέγξει οτιδήποτε νομικά δεσμευτικό, κρίσιμο για την ασφάλεια ή που απευθύνεται σε πελάτες σε πλαίσιο υψηλού ρίσκου.

Από ώρες σε δευτερόλεπτα

Το framework i18n του Django υπερέχει στην εξαγωγή και μεταγλώττιση μεταφράσεων. Το κενό ήταν πάντα στο ίδιο το βήμα μετάφρασης, η κουραστική, επιρρεπής σε σφάλματα εργασία του γεμίσματος εκατοντάδων τιμών msgstr σε πολλαπλές γλώσσες.

Το TranslateBot κλείνει αυτό το κενό. Εγκαταστήστε το, κατευθύνετέ το σε έναν πάροχο AI και τρέξτε μία εντολή. Τα νέα string μεταφράζονται. Τα υπάρχοντα string παραμένουν ανέγγιχτα. Τα placeholder παραμένουν ανέπαφα. Το CI πιάνει οτιδήποτε ξεφεύγει.

Τα αρχεία .po σας σταματούν να είναι αγγαρεία και γίνονται απλώς ένα ακόμη μέρος του build.

pip install translatebot-django

Ξεκινήστε στο translatebot.dev.