How to Add Multilingual Support in Django with Django-parler

If you're building a Django app that needs to support more than one language, Django's built-in internationalisation (i18n) is a decent start. But if you want to go further — like translating model fields, managing multilingual content, and switching language context dynamically — Django-parler is the tool you want.

This guide is aimed at beginners and covers everything from installation to usage, with best practices and practical examples.

---

🌍 Why Use Django-parler?

Django itself provides tools for translating strings in templates and Python code. Still, it doesn't offer a clean way to make database models translatable — to have fields that store multiple language versions.

Django-parler solves this with a well-designed API and seamless integration into Django admin and queries.

---

🔧 Installation and Basic Configuration

First, install the package:

pip install django-parler

Then, add it to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    ...
    'parler',
]

Set your supported languages:

LANGUAGE_CODE = 'en'

LANGUAGES = [
    ('en', 'English'),
    ('pl', 'Polski'),
]

PARLER_LANGUAGES = {
    None: (
        {'code': 'en'},
        {'code': 'pl'},
    ),
    'default': {
        'fallbacks': ['en'],
        'hide_untranslated': False,
    },
}

---

🧱 Making a Model Translatable

Let's say you want to create a Category model in which each language's name and slug should differ.

Here's how to do it with parler:

from django.db import models
from parler.models import TranslatableModel, TranslatedFields

class Category(TranslatableModel):
    translations = TranslatedFields(
        name=models.CharField(max_length=200),
        slug=models.SlugField(max_length=200, unique=True),
    )

    def __str__(self):
        return self.safe_translation_getter('name', any_language=True)

Key points:

• Use TranslatableModel as your base class.
• Define translatable fields inside TranslatedFields().
• Use safe_translation_getter() to safely get the translated value.

---

🛠 Using Translations in the Admin

Django-parler provides an admin mixin to show translation tabs automatically:

from django.contrib import admin
from parler.admin import TranslatableAdmin
from .models import Category

@admin.register(Category)
class CategoryAdmin(TranslatableAdmin):
    list_display = ('__str__',)

You'll now see tabs for each language when editing an object in the admin.

---

🔍 Querying Translatable Models

To avoid duplicate entries or incorrect results, always use .translated() when querying:

from .models import Category

# Only get categories that are translated into the current language
Category.objects.translated('pl').filter(translations__is_published=True)

Or to get only those that exist in the current request's language:

from django.utils.translation import get_language

Category.objects.translated(get_language()).all()

⚠️ Avoid using .filter(translations__...) without .translated(...) or .distinct() — this can lead to duplicate rows in querysets.

---

🎯 Rendering Translations in Templates

Use safe_translation_getter() to access values in templates:

{{ category.safe_translation_getter:"name" }}

Or use the standard property (like category.name) if you're sure the model is correctly translated in the context.

---

🧪 Testing Translations

Use Django's override context to test translations:

from django.utils.translation import override

with override('pl'):
    category = Category.objects.first()
    print(category.name)  # Should be in Polish

---

🧹 Best Practices

• Use safe_translation_getter to prevent NoneType errors.
• Always use .translated() when filtering by translatable fields.
• Never mix translated and untranslated queries unless you use .distinct().
• Use admin mixins to have a smooth experience when editing translations.
• Don't duplicate logic — define fallbacks and supported languages in one place (settings.py).

---

✅ Summary

Django-parler is a powerful tool for multilingual content in Django. With minimal configuration, you can:

• Translate model fields.
• Filter and fetch content in the current language.
• Provide a seamless admin experience.

Stay tuned, and happy translating! 🌍