or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

admin-integration.mdcore-registration.mdfield-management.mdforms-integration.mdindex.mdquery-interface.mdutils-configuration.md
tile.json

tessl/pypi-django-modeltranslation

Translates Django models using a registration approach without modifying original model classes.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/django-modeltranslation@0.19.x

To install, run

npx @tessl/cli install tessl/pypi-django-modeltranslation@0.19.0

index.mddocs/

Django Modeltranslation

A comprehensive Django extension that enables translation of model fields without modifying original model classes. Uses a registration-based approach similar to Django's admin system, storing translation fields in the same database table to avoid expensive joins.

Package Information

  • Package Name: django-modeltranslation
  • Language: Python
  • Installation: pip install django-modeltranslation
  • Django Version: >= 4.2
  • Python Version: >= 3.9

Core Imports

from modeltranslation.translator import register, TranslationOptions

Most common imports:

from modeltranslation.translator import register, TranslationOptions, translator
from modeltranslation.admin import TranslationAdmin, TranslationTabularInline, TranslationStackedInline

Basic Usage

# models.py
from django.db import models

class News(models.Model):
    title = models.CharField(max_length=255)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

# translation.py
from modeltranslation.translator import register, TranslationOptions
from .models import News

@register(News)
class NewsTranslationOptions(TranslationOptions):
    fields = ('title', 'content')

# admin.py (optional)
from django.contrib import admin
from modeltranslation.admin import TranslationAdmin
from .models import News

@admin.register(News)
class NewsAdmin(TranslationAdmin):
    list_display = ('title', 'created_at')

After registration, the model automatically gets translation fields:

  • title_en, title_fr, title_de (based on LANGUAGES setting)
  • content_en, content_fr, content_de

Architecture

Django Modeltranslation follows a registration-based architecture with several key components:

  • Registration System: Uses decorators and options classes to define translatable fields
  • Field Proxy System: Dynamically adds translation fields to models without modifying original classes
  • Admin Integration: Seamlessly integrates with Django admin for translation management
  • Query Rewriting: Automatically rewrites database queries to use appropriate language fields
  • Fallback System: Provides configurable fallback languages when translations are missing

This design enables the same app to work with or without translations, providing maximum reusability across Django projects.

Capabilities

Core Registration

Central registration system for defining translatable model fields using decorators and options patterns. Provides the foundation for all translation functionality.

def register(model_or_iterable, **options):
    """Decorator for registering models with translation options."""

class TranslationOptions:
    """Base class for defining translation field options."""
    fields = ()
    empty_values = None
    required_languages = None
    fallback_languages = None
    fallback_values = None
    fallback_undefined = None

class Translator:
    """Main translator class managing model registrations."""
    def register(self, model_or_iterable, opts_class, **options): ...
    def unregister(self, model_or_iterable): ...
    def get_options_for_model(self, model): ...
    def get_registered_models(self): ...

translator: Translator  # Global translator instance

Core Registration

Admin Integration

Admin classes and mixins providing seamless integration with Django's admin interface for managing translations.

class TranslationAdmin(admin.ModelAdmin):
    """ModelAdmin subclass with translation support."""

class TranslationTabularInline(admin.TabularInline):
    """TabularInline with translation support."""

class TranslationStackedInline(admin.StackedInline):
    """StackedInline with translation support."""

class TranslationGenericTabularInline(GenericTabularInline):
    """GenericTabularInline with translation support."""

class TranslationGenericStackedInline(GenericStackedInline):
    """GenericStackedInline with translation support."""

Admin Integration

Field Management

Translation field types, descriptors, and factory functions for creating and managing multilingual model fields.

class TranslationField:
    """Base class for translation fields."""
    
def create_translation_field(model, field_name, lang, empty_value):
    """Factory function for creating translation fields."""

def field_factory(baseclass):
    """Factory for creating translation field classes."""

class TranslationFieldDescriptor:
    """Field descriptor for translation fields."""

class NONE:
    """Sentinel class for undefined translation values."""

SUPPORTED_FIELDS: tuple  # Tuple of supported Django field types

Field Management

Query Interface

Multilingual managers and querysets that automatically handle language-specific database queries and provide fallback functionality.

class MultilingualManager(models.Manager):
    """Manager for multilingual models."""

class MultilingualQuerySet(models.QuerySet):
    """QuerySet for multilingual models."""

class MultilingualQuerysetManager(MultilingualManager):
    """Combined manager/queryset for multilingual models."""

def rewrite_lookup_key(model, lookup_key):
    """Rewrite lookup keys for translated fields."""

def get_translatable_fields_for_model(model):
    """Get translatable field names for model."""

Query Interface

Forms Integration

Form classes and field types specifically designed for handling translations in Django forms.

class TranslationModelForm(forms.ModelForm):
    """ModelForm subclass for translated models."""

class NullCharField(forms.CharField):
    """CharField that returns None for empty values."""

class NullableField(forms.Field):
    """Field mixin for nullable values."""

Forms Integration

Utils and Configuration

Utility functions for language handling, field name building, and configuration management.

def get_language():
    """Get active language guaranteed to be in settings."""

def get_translation_fields(*fields):
    """Get localized field names for given fields."""

def build_localized_fieldname(field_name, lang):
    """Build localized field name."""

def auto_populate(sender, instance, **kwargs):
    """Auto-populate translation fields."""

def auto_populate_mode(mode):
    """Context manager for auto-populate mode."""

def fallbacks_disabled():
    """Context manager to disable fallbacks."""

# Configuration constants
AVAILABLE_LANGUAGES: list
DEFAULT_LANGUAGE: str
FALLBACK_LANGUAGES: dict
ENABLE_FALLBACKS: bool
AUTO_POPULATE: bool
CUSTOM_FIELDS: tuple

Utils and Configuration

Management Commands

Django Modeltranslation provides management commands for database synchronization:

  • sync_translation_fields - Synchronize translation fields in database schema
  • update_translation_fields - Update translation field values
  • loaddata - Extended loaddata command with translation support

Exception Types

class AlreadyRegistered(Exception):
    """Raised when model is already registered for translation."""

class NotRegistered(Exception):
    """Raised when model is not registered for translation."""

class DescendantRegistered(Exception):
    """Raised when descendant is already registered."""