{"id":4512,"library":"django-modeltranslation","title":"Django Modeltranslation","description":"django-modeltranslation is a Django application that allows you to translate fields of your models into multiple languages. It uses a registration approach, dynamically adding translation fields to your models based on settings. The current version is 0.20.2, and it maintains a regular release cadence with patch and minor updates.","status":"active","version":"0.20.2","language":"python","source_language":"en","source_url":"https://github.com/deschler/django-modeltranslation","tags":["django","i18n","internationalization","translation","models","admin"],"install":[{"cmd":"pip install django-modeltranslation","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This is a Django application and requires Django to run. Version 0.20.x requires Django 3.2+.","package":"Django","optional":false},{"reason":"Required if you plan to translate ImageField or FileField type fields.","package":"Pillow","optional":true}],"imports":[{"symbol":"register","correct":"from modeltranslation.decorators import register"},{"symbol":"TranslationOptions","correct":"from modeltranslation.translator import TranslationOptions"},{"note":"The `translator` object for programmatic registration is found in `modeltranslation.translator`, not `modeltranslation.manager` (which is for ModelTranslationManager).","wrong":"from modeltranslation.manager import translator","symbol":"translator","correct":"from modeltranslation.translator import translator"},{"symbol":"TranslationAdmin","correct":"from modeltranslation.admin import TranslationAdmin"}],"quickstart":{"code":"# --- settings.py ---\n# Add 'modeltranslation' and your app to INSTALLED_APPS\nINSTALLED_APPS = [\n    # ... other apps\n    'modeltranslation',\n    'yourapp', # Your Django app containing translated models\n]\n\n# Define the languages available for translation\nLANGUAGES = (\n    ('en', 'English'),\n    ('fr', 'French'),\n    # Add other languages as needed\n)\n\n# Optional: Configure fallback languages behavior\n# FALLBACK_LANGUAGES = {'default': ('en', 'fr'), 'fr': ('en',)}\n\n\n# --- yourapp/models.py ---\nfrom django.db import models\n\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    description = models.TextField(blank=True, null=True)\n    price = models.DecimalField(max_digits=10, decimal_places=2)\n\n    def __str__(self):\n        return self.name\n\n# --- yourapp/translation.py ---\nfrom modeltranslation.decorators import register\nfrom modeltranslation.translator import TranslationOptions\nfrom .models import Product\n\n@register(Product)\nclass ProductTranslationOptions(TranslationOptions):\n    fields = ('name', 'description',)\n\n# --- yourapp/admin.py ---\nfrom django.contrib import admin\nfrom modeltranslation.admin import TranslationAdmin\nfrom .models import Product\n\n@admin.register(Product)\nclass ProductAdmin(TranslationAdmin):\n    list_display = ('name', 'price',) # 'name' will automatically display the current language\n    group_fieldsets = True # Optional: Groups translation fields under tabs in the admin\n    # Other Django Admin options can be added here\n\n# --- Post-setup steps ---\n# After adding the above code:\n# 1. Run database migrations to create translation fields:\n#    python manage.py makemigrations yourapp\n#    python manage.py migrate\n# 2. Synchronize translation fields (crucial for initial setup and field changes):\n#    python manage.py sync_translation_fields\n\n# --- Accessing translated data ---\n# from django.utils import translation\n# product_instance = Product.objects.first()\n\n# with translation.override('en'):\n#     print(product_instance.name) # Accesses 'name_en'\n\n# with translation.override('fr'):\n#     print(product_instance.name) # Accesses 'name_fr'\n\n# print(product_instance.name_en) # Direct access to English field\n# print(product_instance.get_name_fr()) # Helper for specific language","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade 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).","message":"Version 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.","severity":"breaking","affected_versions":"0.20.0 and above"},{"fix":"Thoroughly 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.","message":"The 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.","severity":"breaking","affected_versions":"0.20.0 and above"},{"fix":"Always 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.","message":"After 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"In your `admin.py`, ensure your model admin class inherits from `TranslationAdmin` (e.g., `class MyModelAdmin(TranslationAdmin): ...`).","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefer `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.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.20.2':41 'ad':28 'admin':59 'allow':11 'applic':9 'approach':26 'base':34 'cadenc':48 'current':38 'django':1,4,8,54 'django-modeltransl':3 'dynam':27 'field':15,30 'i18n':55 'internation':56 'languag':21 'maintain':44 'minor':52 'model':18,33,58 'modeltransl':2,5 'multipl':20 'patch':50 'registr':25 'regular':46 'releas':47 'set':36 'translat':14,29,57 'updat':53 'use':23 'version':39","created_at":"2026-04-12T13:55:49.730666+00:00","updated_at":"2026-04-16T14:32:32.250409+00:00","problems":[{"fix":"Ensure the package is installed: `pip install django-modeltranslation`. Then, add `'modeltranslation'` to your `INSTALLED_APPS` in `settings.py`, preferably before `django.contrib.admin`.","cause":"The `django-modeltranslation` package is not installed, not added to `INSTALLED_APPS`, or not correctly found in the Python environment.","error":"ModuleNotFoundError: No module named 'modeltranslation'"},{"fix":"Create 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',);`","cause":"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.","error":"Model not registered for translation"},{"fix":"Upgrade 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.","cause":"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.","error":"TypeError: 'type' object is not subscriptable"},{"fix":"Review 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`.","cause":"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.","error":"ValueError: Error adding translation field. Model already contains the field"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.20.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/deschler/django-modeltranslation","docs":"https://django-modeltranslation.readthedocs.org/en/latest","changelog":"https://github.com/deschler/django-modeltranslation/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/django-modeltranslation/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}