Як перекладати вміст бази даних Django за допомогою AI

Якщо ви працювали з вбудованим фреймворком інтернаціоналізації (i18n) Django, ви знаєте, що він добре обробляє статичні рядки. Обгортання тексту в gettext() або використання тегу шаблону {% trans %} витягує рядки у файли .po, які заповнюють перекладачі. Система перевірена часом і чудово працює для коду та шаблонів.

Але що робити з контентом, який зберігається у вашій базі даних?

Назви продуктів, заголовки статей, описи категорій, відповіді на FAQ, контент, створений користувачами. Нічого з цього немає у вашому вихідному коді. Команда makemessages Django ніколи не знайде це, і файли .po тут не допоможуть. Якщо ваш додаток надає динамічний контент користувачам кількома мовами, вам потрібна інша стратегія.

Ось як це зробити: використовуйте django-modeltranslation для додавання перекладних полів до ваших моделей, а потім автоматизуйте переклад за допомогою AI, використовуючи TranslateBot.

Пакети для перекладу бази даних Django

Кілька сторонніх пакетів вирішують проблему перекладу бази даних, кожен з різною архітектурою.

django-modeltranslation

Додає мовні колонки безпосередньо до існуючих таблиць. Поле title стає title_en, title_de, title_fr тощо. Запити залишаються швидкими, оскільки все знаходиться в одній таблиці. Інтерфейс адміністратора показує всі мови поруч.

Переваги: Без JOIN, швидкі запити, прозорий доступ через дескриптори полів, зріла екосистема
Недоліки: Зміни схеми для кожної нової мови, ширші таблиці

django-parler

Створює окрему таблицю перекладів для кожної моделі. Оригінальна таблиця залишається чистою, а переклади зберігаються у пов'язаній таблиці, з'єднаній зовнішнім ключем.

Переваги: Чиста схема, легко додавати мови без міграцій
Недоліки: Потрібні JOIN для перекладеного контенту, трохи складніші шаблони запитів

django-translations

Використовує єдину таблицю перекладів із загальним зовнішнім ключем, що вказує на будь-яку модель. Усі переклади для всіх моделей потрапляють в одну таблицю.

Переваги: Мінімальні зміни схеми, працює з будь-якою моделлю
Недоліки: Запити із загальним зовнішнім ключем можуть бути повільними, менш прозорий API

Ручне поле JSON

Ви можете зберігати переклади в JSONField:

class Product(models.Model):
    name_translations = models.JSONField(default=dict)
    # {"en": "Running Shoes", "de": "Laufschuhe", "fr": "Chaussures de course"}

Переваги: Без додаткових залежностей, гнучкість
Недоліки: Без інтеграції з ORM, без підтримки адміністратора, все вручну

Який обрати?

Для більшості проектів django-modeltranslation -- найкращий вибір. Це найзріліший пакет, має найкращу інтеграцію з адміністратором Django і зберігає всі дані в одній таблиці для швидких запитів. Компроміс (ширші таблиці та міграція для кожної нової мови) є прийнятним для переважної більшості додатків. Решта цього посібника використовує django-modeltranslation.

Налаштування django-modeltranslation крок за кроком

Крок 1: Встановіть пакет

TranslateBot включає django-modeltranslation як необов'язкову залежність. Встановіть обидва одразу:

pip install translatebot-django[modeltranslation]

Або якщо ви використовуєте uv:

uv add --dev translatebot-django[modeltranslation]

Крок 2: Налаштуйте параметри Django

Дві речі важливі в settings.py: порядок додатків та список мов.

# settings.py

INSTALLED_APPS = [
    'modeltranslation',          # Must be BEFORE django.contrib.admin
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Your apps
    'shop',
    'translatebot_django',
]

LANGUAGE_CODE = 'en'

LANGUAGES = [
    ('en', 'English'),
    ('de', 'German'),
    ('fr', 'French'),
    ('nl', 'Dutch'),
]

Додаток modeltranslation повинен бути перед django.contrib.admin, щоб він міг пропатчити класи адміністратора для відображення полів перекладу.

Крок 3: Зареєструйте моделі для перекладу

Створіть файл translation.py у кожному додатку, що має моделі для перекладу. Для додатку інтернет-магазину:

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product, Category


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')


@register(Category)
class CategoryTranslationOptions(TranslationOptions):
    fields = ('name', 'description')

Включайте лише поля, що містять текст, зрозумілий людині. Не реєструйте поля на кшталт slug, price або sku.

Крок 4: Створіть та виконайте міграції

python manage.py makemigrations
python manage.py migrate

Після цього таблиця shop_product матиме нові колонки:

Column	Type
`name`	varchar(200)
`name_en`	varchar(200)
`name_de`	varchar(200)
`name_fr`	varchar(200)
`name_nl`	varchar(200)
`description`	text
`description_en`	text
`description_de`	text
`description_fr`	text
`description_nl`	text
`short_description`	text
`short_description_en`	text
`short_description_de`	text
`short_description_fr`	text
`short_description_nl`	text

Кожна мова, визначена в LANGUAGES, отримує власну колонку для кожного зареєстрованого поля.

Проблема: Порожні поля перекладу

Тепер у вас є схема, але кожна колонка _de, _fr та _nl порожня. Якщо у вас 500 продуктів із 3 перекладними полями та 3 цільовими мовами, це 4 500 порожніх полів, які чекають на заповнення.

Перекладати цей контент вручну нереалістично. Навіть із професійним перекладацьким сервісом вам потрібно експортувати дані, надіслати їх, дочекатися доставки та імпортувати результати назад. Для невеликої команди або розробника-одинака це зазвичай означає, що функціонал ніколи не виходить у світ.

Тут і з'являється TranslateBot.

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

Команда управління translate в TranslateBot може заповнити всі порожні поля за допомогою AI. Спочатку налаштуйте свій API-ключ:

# settings.py

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"  # Fast and cost-effective

Потім перекладіть усі зареєстровані моделі на цільову мову:

python manage.py translate --target-lang de --models

Ця єдина команда знаходить кожну модель, зареєстровану в django-modeltranslation, визначає поля, порожні для цільової мови, та заповнює їх перекладами, згенерованими AI.

Переклад конкретних моделей

Якщо ви хочете перекласти лише продукти, а не категорії:

python manage.py translate --target-lang de --models Product

Або кілька конкретних моделей:

python manage.py translate --target-lang de --models Product Category

Попередній перегляд із dry run

Завжди переглядайте результат перед записом у базу даних:

python manage.py translate --target-lang de --models --dry-run

Це показує точно, що буде перекладено, без зміни жодних записів.

Повторний переклад існуючого контенту

За замовчуванням TranslateBot пропускає поля, які вже мають переклад. Щоб перезаписати існуючі переклади (наприклад, після покращення моделі AI або додавання контексту):

python manage.py translate --target-lang de --models --overwrite

Переклад усіх мов одразу

Якщо ви не вказуєте --target-lang і маєте LANGUAGES, визначений у налаштуваннях, TranslateBot перекладає на всі налаштовані мови:

python manage.py translate --models

Як працює конвеєр перекладу

Ось що відбувається при виконанні команди translate.

Виявлення. TranslateBot запитує реєстр django-modeltranslation, щоб знайти всі зареєстровані моделі та їх перекладні поля.
Визначення джерела. Для кожного запису зчитується вихідний контент. Спочатку перевіряється базове поле (наприклад, name), потім відбувається fallback до першого заповненого мовного поля (наприклад, name_en). Записи без вихідного контенту пропускаються.
Пакетна обробка. Записи групуються в пакети та надсилаються до провайдера AI. Це забезпечує ефективність API-викликів та запобігає перевищенню лімітів швидкості.
Переклад. Кожен пакет перекладається за допомогою налаштованої моделі AI. Ви можете використовувати будь-якого провайдера LLM, підтримуваного LiteLLM (OpenAI, Anthropic, Google, Azure та багато інших) або DeepL.
Атомарний запис. Усі оновлення бази даних для сесії перекладу обгорнуті в одну транзакцію. Якщо щось піде не так, наприклад помилка API або порушення обмеження бази даних, жодні часткові дані не зберігаються. Все або нічого.

Повний приклад робочого процесу

Ось повний приклад від визначення моделі до перекладеного контенту з використанням моделі Product для електронної комерції.

Визначення моделі

# shop/models.py

from django.db import models


class Product(models.Model):
    name = models.CharField(max_length=200)
    description = models.TextField()
    short_description = models.CharField(max_length=500, blank=True)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    sku = models.CharField(max_length=50, unique=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

Реєстрація для перекладу

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')

Виконання міграцій

python manage.py makemigrations shop
python manage.py migrate

Додавання контексту перекладу (необов'язково)

Створіть файл TRANSLATING.md у корені проекту, щоб надати AI контекст про предметну область ваших продуктів:

# Translation Context

## About This Project
E-commerce store for outdoor sports equipment.

## Terminology
- "trail runners" refers to trail running shoes, not people
- Keep brand names (Nike, Salomon, Arc'teryx) untranslated
- "Gore-Tex" is a brand name, do not translate

## Tone
- Use informal "du" form in German
- Product descriptions should sound enthusiastic but not exaggerated

Переклад

# Preview first
python manage.py translate --target-lang de --models Product --dry-run

# Apply translations
python manage.py translate --target-lang de --models Product

Вивід:

Translating Product model fields to German (de)...
Found 142 products with untranslated fields
Translating batch 1/15...
Translating batch 2/15...
...
Translating batch 15/15...
Successfully translated 142 products

Перевірка в адміністраторі

Відкрийте адміністратор Django та перейдіть до будь-якого продукту. Ви побачите заповнені поля перекладу:

Name [de]: Ultraleichte Trail-Laufschuhe
Description [de]: Diese leichten Trail-Laufschuhe bieten hervorragenden Grip...
Short description [de]: Leicht, schnell und griffig auf jedem Untergrund.

Повторіть для кожної цільової мови:

python manage.py translate --target-lang fr --models Product
python manage.py translate --target-lang nl --models Product

Або перекладіть усі мови одразу:

python manage.py translate --models Product

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

Зробіть резервну копію бази даних перед запуском масових перекладів на продакшені. TranslateBot використовує атомарні транзакції, тому невдалий запуск не залишить часткових даних. Але наявність резервної копії дає вам можливість відкотити зміни, якщо якість перекладу не відповідає очікуванням.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Спочатку використовуйте dry run. Завжди запускайте з --dry-run перед застосуванням перекладів до нової моделі або мови. Перегляньте вивід, щоб переконатися, що вихідний контент визначається правильно, а переклади виглядають розумно.

Перекладайте по одній моделі для великих баз даних. Це полегшує перегляд результатів та повторний запуск конкретних моделей за потреби.

python manage.py translate --target-lang de --models Product
python manage.py translate --target-lang de --models Category
python manage.py translate --target-lang de --models Article

Додайте контекст перекладу. Файл TRANSLATING.md із термінологією, специфічною для домену, та рекомендаціями щодо тону значно покращує якість перекладу. Це особливо важливо для спеціалізованих галузей, таких як медицина, юриспруденція або технічні продукти.

Тримайте мову джерела заповненою. TranslateBot читає з базового поля або поля мови джерела. Переконайтеся, що ваш процес введення даних завжди заповнює мову джерела. Порожні поля джерела означають порожні переклади.

Поєднайте з перекладом PO-файлів для повного покриття. Перекладіть як рядки коду, так і контент бази даних:

# Static strings in code and templates
python manage.py makemessages -l de -l fr -l nl
python manage.py translate
python manage.py compilemessages

# Dynamic content in the database
python manage.py translate --models

Таким чином кожен рядок, який бачать ваші користувачі, чи то з шаблону, чи з бази даних, буде перекладений.

Наступні кроки

Прочитайте повну довідку команд з усіма доступними опціями
Налаштуйте інтеграцію з CI для автоматичної перевірки відсутніх перекладів
Дослідіть підтримувані моделі AI, щоб знайти найкращий баланс між якістю та вартістю для вашого проекту