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
```