Django i18n: Повний посібник з автоматизації перекладу .po файлів

Якщо ви коли-небудь випускали додаток Django більш ніж однією мовою, ви знаєте цю процедуру. Ви обгортаєте свої рядки в gettext(), запускаєте makemessages, відкриваєте файл .po із сотнями записів і починаєте перекладати рядок за рядком. Для двох мов і п'ятдесяти рядків це терпимо. Для шести мов і п'ятисот рядків це цілий робочий день, який ви ніколи не повернете.

Цей посібник охоплює pipeline інтернаціоналізації (i18n) Django від початку до кінця, пояснює, де він дає збій, і показує, як автоматизувати болючу частину за допомогою перекладу на основі AI.

Стандартний робочий процес Django i18n

Вбудована система i18n Django добре спроектована. Основний цикл виглядає так:

Крок 1: Позначте рядки для перекладу у вашому коді Python та шаблонах:

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: Витягніть рядки у файли .po:

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

Це сканує всю кодову базу і генерує один файл .po на мову, що містить кожен рядок для перекладу:

#: 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 рядків для перекладу. Помножте це на кількість цільових мов, і ви побачите серйозні витрати часу.

Це не теоретична скарга. У відомому треді Django Forum розробник повідомив, що витрачає понад 8 годин на файл .po на ручний переклад. Один із основних контриб'юторів Django описав, що витратив понад 10 годин на включення перекладів, надісланих спільнотою, в один реліз, переважно на перевірку, виправлення форматування та виправлення зламаних placeholder'ів.

Проблеми накопичуються з часом:

• Placeholder'и ламаються. Скопіюйте рядок на кшталт Welcome, %(name)s! у Google Translate, і часто отримаєте Willkommen, %(Name)s! або Bienvenue, %(nom)s!. Це тонке пошкодження спричиняє помилки під час виконання.
• Узгодженість розмивається. Без глосарія "dashboard" перекладається як "Instrumententafel" в одному файлі та "Dashboard" в іншому. Через три місяці ніхто не пам'ятає, що було навмисним.
• Спринти додають рядки. Кожна гілка з новою функціональністю додає нові рядки для перекладу. Навіть якщо ви заплатили за повний переклад минулого кварталу, тепер у вас 40 неперекладених записів, розкиданих по файлах .po.
• AI-помічники допомагають один раз. Ви можете вставити файл .po у ChatGPT або Claude та отримати пристойні результати. Але в наступному спринті, коли з'являться 15 нових рядків, ви пишете промпт з нуля, перекладаєте весь файл заново і сподіваєтесь, що він залишиться узгодженим із тим, що вже було.

Головна причина в тому, що переклад розглядається як одноразова подія замість поступового, повторюваного процесу.

Автоматизація перекладу за допомогою AI

Ідея проста: замість того, щоб людина відкривала кожен файл .po і заповнювала значення msgstr, інструмент читає файл, відправляє неперекладені рядки до моделі 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 моделей, змінивши один рядок:

Для 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

Три команди. Кожна мова. Кожен спринт.

Інкрементальний за задумом

Найважливіша функція для повторюваного робочого процесу — інкрементальний переклад. TranslateBot перекладає лише записи, де msgstr порожній. Якщо у вас 500 рядків і 15 нових у цьому спринті, лише ці 15 відправляються до API.

Це важливо з практичних причин:

1. Вартість. Ви платите лише за нові рядки, а не за весь файл.
2. Швидкість. Переклад 15 рядків займає секунди, а не хвилини.
3. Стабільність. Переклади, які ви вже переглянули та затвердили, ніколи не перезаписуються (якщо ви явно не передасте --overwrite).

Безпека placeholder'ів

Django використовує кілька форматів placeholder'ів: %(name)s, %s, %d, {0}, {name} та вбудовані HTML-теги на кшталт <strong> або <a href="...">. Якщо будь-який з них буде зіпсований при перекладі, ви отримаєте помилки під час виконання або зламану розмітку.

TranslateBot інструктує модель AI зберігати всі формати placeholder'ів і валідує вивід. Рядок на кшталт:

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 для окремих додатків зі спеціалізованою термінологією. Модуль медичних записів та модуль виставлення рахунків можуть мати власні глосарії.

Попередній перегляд перед комітом

Прапор --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, розроблену для 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 і збій збірки:

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. Додайте нові рядки для перекладу в гілці з новою функціональністю.
2. CI не проходить, оскільки ці рядки неперекладені.
3. Запустіть python manage.py translate локально.
4. Закомітьте оновлені файли .po.
5. CI проходить.

Переклади ніколи тихо не розсинхронізуються.

Переклад вмісту бази даних

Якщо ваш додаток зберігає вміст для перекладу в базі даних (назви продуктів, заголовки блогу, мітки категорій), 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 рядками для перекладу на 5 мов:

Цифри змінюються залежно від кількості рядків та цільових мов, але різниця на порядок є стабільною. Для поточного обслуговування (переклад 20-50 нових рядків, що додаються кожен спринт) вартість AI фактично дорівнює нулю.

Найкращі практики

Почніть з --dry-run. Перед першим реальним запуском перекладу подивіться попередньо, що станеться. Це зміцнює впевненість та виявляє проблеми конфігурації на ранньому етапі.

Закомітьте файли .po перед перекладом. Якщо щось піде не так, git checkout миттєво поверне вас до чистого стану.

Напишіть TRANSLATING.md з першого дня. Навіть короткий файл з описом проекту та кількома правилами термінології помітно покращує якість перекладу.

Додайте check_translations до CI. Цей єдиний крок запобігає найпоширенішому режиму відмови i18n: рядки, які були позначені для перекладу, але ніколи фактично не перекладені.

Використовуйте gpt-4o-mini або DeepL для економічної ефективності. Зберігайте преміальні моделі на кшталт GPT-4o або Claude для проектів, де точність має значення, як-от маркетинговий текст, юридичний текст або доменна термінологія.

Перевіряйте критичні рядки. Переклади AI достатньо хороші для більшості тексту інтерфейсу, але попросіть носія мови перевірити все, що є юридично зобов'язуючим, критичним для безпеки або орієнтованим на клієнта у контексті високих ставок.

Від годин до секунд

Фреймворк i18n Django відмінно справляється з вилученням та компіляцією перекладів. Прогалина завжди була на самому кроці перекладу — нудній, схильній до помилок роботі з заповнення сотень значень msgstr кількома мовами.

TranslateBot закриває цю прогалину. Встановіть його, спрямуйте на провайдера AI та запустіть одну команду. Нові рядки перекладаються. Існуючі рядки залишаються недоторканими. Placeholder'и залишаються цілими. CI ловить все, що проскочить.

Ваші файли .po перестають бути тягарем і стають просто ще однією частиною збірки.

pip install translatebot-django

Почніть на translatebot.dev.