{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}