0
# Django Modeltranslation
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: django-modeltranslation
7
- **Language**: Python
8
- **Installation**: `pip install django-modeltranslation`
9
- **Django Version**: >= 4.2
10
- **Python Version**: >= 3.9
11

12
## Core Imports
13

14
```python
15
from modeltranslation.translator import register, TranslationOptions
16
```
17

18
Most common imports:
19

20
```python
21
from modeltranslation.translator import register, TranslationOptions, translator
22
from modeltranslation.admin import TranslationAdmin, TranslationTabularInline, TranslationStackedInline
23
```
24

25
## Basic Usage
26

27
```python
28
# models.py
29
from django.db import models
30

31
class News(models.Model):
32
    title = models.CharField(max_length=255)
33
    content = models.TextField()
34
    created_at = models.DateTimeField(auto_now_add=True)
35

36
# translation.py
37
from modeltranslation.translator import register, TranslationOptions
38
from .models import News
39

40
@register(News)
41
class NewsTranslationOptions(TranslationOptions):
42
    fields = ('title', 'content')
43

44
# admin.py (optional)
45
from django.contrib import admin
46
from modeltranslation.admin import TranslationAdmin
47
from .models import News
48

49
@admin.register(News)
50
class NewsAdmin(TranslationAdmin):
51
    list_display = ('title', 'created_at')
52
```
53

54
After registration, the model automatically gets translation fields:
55
- `title_en`, `title_fr`, `title_de` (based on LANGUAGES setting)
56
- `content_en`, `content_fr`, `content_de`
57

58
## Architecture
59

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

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

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

70
## Capabilities
71

72
### Core Registration
73

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

76
```python { .api }
77
def register(model_or_iterable, **options):
78
    """Decorator for registering models with translation options."""
79

80
class TranslationOptions:
81
    """Base class for defining translation field options."""
82
    fields = ()
83
    empty_values = None
84
    required_languages = None
85
    fallback_languages = None
86
    fallback_values = None
87
    fallback_undefined = None
88

89
class Translator:
90
    """Main translator class managing model registrations."""
91
    def register(self, model_or_iterable, opts_class, **options): ...
92
    def unregister(self, model_or_iterable): ...
93
    def get_options_for_model(self, model): ...
94
    def get_registered_models(self): ...
95

96
translator: Translator  # Global translator instance
97
```
98

99
[Core Registration](./core-registration.md)
100

101
### Admin Integration
102

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

105
```python { .api }
106
class TranslationAdmin(admin.ModelAdmin):
107
    """ModelAdmin subclass with translation support."""
108

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

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

115
class TranslationGenericTabularInline(GenericTabularInline):
116
    """GenericTabularInline with translation support."""
117

118
class TranslationGenericStackedInline(GenericStackedInline):
119
    """GenericStackedInline with translation support."""
120
```
121

122
[Admin Integration](./admin-integration.md)
123

124
### Field Management
125

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

128
```python { .api }
129
class TranslationField:
130
    """Base class for translation fields."""
131
    
132
def create_translation_field(model, field_name, lang, empty_value):
133
    """Factory function for creating translation fields."""
134

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

138
class TranslationFieldDescriptor:
139
    """Field descriptor for translation fields."""
140

141
class NONE:
142
    """Sentinel class for undefined translation values."""
143

144
SUPPORTED_FIELDS: tuple  # Tuple of supported Django field types
145
```
146

147
[Field Management](./field-management.md)
148

149
### Query Interface
150

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

153
```python { .api }
154
class MultilingualManager(models.Manager):
155
    """Manager for multilingual models."""
156

157
class MultilingualQuerySet(models.QuerySet):
158
    """QuerySet for multilingual models."""
159

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

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

166
def get_translatable_fields_for_model(model):
167
    """Get translatable field names for model."""
168
```
169

170
[Query Interface](./query-interface.md)
171

172
### Forms Integration
173

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

176
```python { .api }
177
class TranslationModelForm(forms.ModelForm):
178
    """ModelForm subclass for translated models."""
179

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

183
class NullableField(forms.Field):
184
    """Field mixin for nullable values."""
185
```
186

187
[Forms Integration](./forms-integration.md)
188

189
### Utils and Configuration
190

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

193
```python { .api }
194
def get_language():
195
    """Get active language guaranteed to be in settings."""
196

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

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

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

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

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

212
# Configuration constants
213
AVAILABLE_LANGUAGES: list
214
DEFAULT_LANGUAGE: str
215
FALLBACK_LANGUAGES: dict
216
ENABLE_FALLBACKS: bool
217
AUTO_POPULATE: bool
218
CUSTOM_FIELDS: tuple
219
```
220

221
[Utils and Configuration](./utils-configuration.md)
222

223
## Management Commands
224

225
Django Modeltranslation provides management commands for database synchronization:
226

227
- `sync_translation_fields` - Synchronize translation fields in database schema
228
- `update_translation_fields` - Update translation field values
229
- `loaddata` - Extended loaddata command with translation support
230

231
## Exception Types
232

233
```python { .api }
234
class AlreadyRegistered(Exception):
235
    """Raised when model is already registered for translation."""
236

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

240
class DescendantRegistered(Exception):
241
    """Raised when descendant is already registered."""
242
```