Registry /
database / django-modeltranslation
Install & Compatibility
Where this runs
tested against v0.20.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.002s · 67.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.930s · 68MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
register
✓ from modeltranslation.decorators import register
TranslationOptions
✓ from modeltranslation.translator import TranslationOptions
translator
✓ from modeltranslation.translator import translator
✗ from modeltranslation.manager import translator
The `translator` object for programmatic registration is found in `modeltranslation.translator`, not `modeltranslation.manager` (which is for ModelTranslationManager).
TranslationAdmin
✓ from modeltranslation.admin import TranslationAdmin
This quickstart demonstrates the core setup for django-modeltranslation. It includes the necessary `settings.py` configuration, defines a sample model in `yourapp/models.py`, registers it for translation in `yourapp/translation.py`, and integrates it with the Django admin using `TranslationAdmin` in `yourapp/admin.py`. Remember to run `makemigrations`, `migrate`, and `sync_translation_fields` after setup.
# --- settings.py ---
# Add 'modeltranslation' and your app to INSTALLED_APPS
INSTALLED_APPS = [
# ... other apps
'modeltranslation',
'yourapp', # Your Django app containing translated models
]
# Define the languages available for translation
LANGUAGES = (
('en', 'English'),
('fr', 'French'),
# Add other languages as needed
)
# Optional: Configure fallback languages behavior
# FALLBACK_LANGUAGES = {'default': ('en', 'fr'), 'fr': ('en',)}
# --- yourapp/models.py ---
from django.db import models
class Product(models.Model):
name = models.CharField(max_length=255)
description = models.TextField(blank=True, null=True)
price = models.DecimalField(max_digits=10, decimal_places=2)
def __str__(self):
return self.name
# --- yourapp/translation.py ---
from modeltranslation.decorators import register
from modeltranslation.translator import TranslationOptions
from .models import Product
@register(Product)
class ProductTranslationOptions(TranslationOptions):
fields = ('name', 'description',)
# --- yourapp/admin.py ---
from django.contrib import admin
from modeltranslation.admin import TranslationAdmin
from .models import Product
@admin.register(Product)
class ProductAdmin(TranslationAdmin):
list_display = ('name', 'price',) # 'name' will automatically display the current language
group_fieldsets = True # Optional: Groups translation fields under tabs in the admin
# Other Django Admin options can be added here
# --- Post-setup steps ---
# After adding the above code:
# 1. Run database migrations to create translation fields:
# python manage.py makemigrations yourapp
# python manage.py migrate
# 2. Synchronize translation fields (crucial for initial setup and field changes):
# python manage.py sync_translation_fields
# --- Accessing translated data ---
# from django.utils import translation
# product_instance = Product.objects.first()
# with translation.override('en'):
# print(product_instance.name) # Accesses 'name_en'
# with translation.override('fr'):
# print(product_instance.name) # Accesses 'name_fr'
# print(product_instance.name_en) # Direct access to English field
# print(product_instance.get_name_fr()) # Helper for specific language
Debug
Known issues
breakingVersion 0.20.0 introduced significant changes, requiring Python 3.10+ and Django 3.2+. Older versions of Python and Django are no longer supported. Ensure your environment meets these requirements before upgrading.fixUpgrade Python to 3.10+ and Django to 3.2+ or stick to an older django-modeltranslation version compatible with your environment (e.g., 0.19.x for Django 2.2/3.1).
affects: 0.20.0 and above
breakingThe behavior of the `FALLBACK_LANGUAGES` setting changed significantly in version 0.20.0. If `FALLBACK_LANGUAGES` is empty or not set, it now defaults to the `LANGUAGE_CODE` if the explicitly requested language isn't found. This can alter how empty translation fields are resolved, potentially displaying the default language when previously nothing might have been shown. Review your `FALLBACK_LANGUAGES` configuration and application logic.fixThoroughly test your application's language fallback logic after upgrading. Explicitly define `FALLBACK_LANGUAGES` if you rely on specific fallback sequences, or set it to `None` if you want no fallbacks beyond what's built-in for the current language.
affects: 0.20.0 and above
gotchaAfter defining `TranslationOptions` for a model or modifying its translated fields, you MUST run `python manage.py makemigrations`, `python manage.py migrate`, AND then `python manage.py sync_translation_fields`. Failing to run `sync_translation_fields` will result in the actual database columns for translations (e.g., `name_en`, `name_fr`) not being created or updated, leading to `DoesNotExist` or `AttributeError` when accessing them.fixAlways remember the three-step migration process: `makemigrations`, `migrate`, `sync_translation_fields` for any changes affecting translated fields. `sync_translation_fields` is idempotent and safe to run multiple times.
affects: All versions
gotchaFor translated fields to appear and be editable in the Django admin interface, you must use `modeltranslation.admin.TranslationAdmin` (or a subclass) for your registered models, not `django.contrib.admin.ModelAdmin`. Without `TranslationAdmin`, the additional language fields will not be displayed.fixIn your `admin.py`, ensure your model admin class inherits from `TranslationAdmin` (e.g., `class MyModelAdmin(TranslationAdmin): ...`).
affects: All versions
gotchaWhile you can directly access translation fields like `instance.my_field_en`, it's generally better practice to use `instance.my_field` when the current request's language is set correctly (via `django.utils.translation.activate` or `with translation.override`). This allows your code to adapt to the active language automatically. Direct access to `_en` suffixes bypasses language negotiation.fixPrefer `instance.translated_field_name` when possible, especially in templates or views that respect the active language. Use `instance.get_translated_field_name('lang_code')` or direct `instance.translated_field_name_lang_code` only when you specifically need a fixed language translation regardless of the active language. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'modeltranslation'
The `django-modeltranslation` package is not installed, not added to `INSTALLED_APPS`, or not correctly found in the Python environment.
fixEnsure the package is installed: `pip install django-modeltranslation`. Then, add `'modeltranslation'` to your `INSTALLED_APPS` in `settings.py`, preferably before `django.contrib.admin`.
Model not registered for translation
A model intended for translation has not been correctly registered with `django-modeltranslation`'s `translator` in a `translation.py` file within your app, or the `translation.py` file is not being discovered.
fixCreate a `translation.py` file in your app directory (next to `models.py`). In this file, import `register` and `TranslationOptions` from `modeltranslation.translator`, and your model. Then, register your model with a `TranslationOptions` class. Example: `from modeltranslation.translator import register, TranslationOptions; from .models import MyModel; @register(MyModel) class MyModelTranslationOptions(TranslationOptions): fields = ('my_field',);` TypeError: 'type' object is not subscriptable
This error often occurs in older Python versions (e.g., Python 3.8 and below) when using type hints with generic types (like `list[str]` or `tuple[int, ...]`) without `from __future__ import annotations`. `django-modeltranslation`'s internal code or user-defined type hints in `translation.py` or admin files can trigger this.
fixUpgrade to Python 3.9 or higher, or add `from __future__ import annotations` at the top of any file where this type of syntax is used for type hints.
ValueError: Error adding translation field. Model already contains the field
This error typically occurs during `makemigrations` or `migrate` if `django-modeltranslation` attempts to add translated fields (e.g., `field_en`, `field_fr`) to a model that already has fields with those exact names, usually due to manual field creation or a previous incomplete setup.
fixReview your model definitions (`models.py`) and `translation.py` to ensure no manual fields conflict with the automatically generated translation fields. If you are updating an existing project, you might need to manually remove conflicting fields from the database or squash migrations after correcting the model definition. Ensure you run `makemigrations` and `migrate` after defining or changing `TranslationOptions`.
Upgrade
Version history
0.20.3latest on PyPI · released Apr 14, 2026
Audit
Dependencies
DjangorequiredThis is a Django application and requires Django to run. Version 0.20.x requires Django 3.2+.
PillowoptionalRequired if you plan to translate ImageField or FileField type fields.