bc-model-translator

This is a lightweight and extensible Django app for model field translations based on the current active language.

Supports dynamic field registration, localized querying, and transparent field access using Python magic.

✨ Features

• Automatic creation of translated fields (name_en, name_ru, etc.)
• Transparent access to localized values via model attributes
• Language-aware filter(), get(), and exclude() on QuerySets
• Simple registration system via decorators
• Integration-ready: autodiscovery of translation.py files
• Per-language field customization — configure attributes like verbose_name, max_length, default, etc., per field and language via BcTranslationFieldParams

🚀 Installation

pip install bc-model-translator

Add the app to INSTALLED_APPS:

⚙️ Configuration

1. Add the app to INSTALLED_APPS

INSTALLED_APPS = [
    ...
    "bc_modeltranslater",
]

2. Available settings:

# Temporarily disable translation registration if needed
MODELTRANSLATION_ENABLE_REGISTRATIONS = True

# Filename to look for in each app (default: "translation")
TRANS_FILENAME = "translation"

The TRANS_FILENAME setting defines the file name (without .py) that the app will look for in each Django app to discover translation registration.

🛠️ Usage

Create a translation.py file inside your Django app.

This file is automatically discovered on startup.

# your_app/translation.py

from bc_modeltranslater import register, BcTranslationOptions, BcTranslationField, BcTranslationFieldParams
from .models import TestModel

@register(TestModel)
class SymptomTranslationOptions(BcTranslationOptions):
    fields = [
        BcTranslationField(field_name="name"),
        BcTranslationField(
            field_name="desc",
            params={
                "fr": BcTranslationFieldParams(verbose_name="Description in French"),
                "kk": BcTranslationFieldParams(verbose_name="Kazakh description"),
            }
        )
    ]

🛠️ Available field parameters

BcTranslationFieldParams(
    verbose_name: str | None = None,
    default: str | None = None,
    blank: bool | None = None,
    help_text: str | None = None,
    max_length: int | None = None,
    null: bool | None = None,
    unique: bool | None = None
)

You can define different attributes per language using the params dictionary, where each key is a language code ("en", "ru", "fr", etc.).

🔍 Querying

All query methods automatically use the active language:

from django.utils.translation import activate

activate("ru")
TestModel.objects.filter(name="Имя")  # Filters by name_ru

🧠 Field Access

You can access localized values through normal attribute access:

obj = TestModel.objects.first()
print(obj.name)  # Returns name_ru or name_en depending on current language