Skip to main content

Modeltranslation is an utility to translate Django model fields.

Project description

Versión en español en


This application allows you use Django model translations easily. Everything is based on FieldTranslation, a class that stores the translation of each field of your application models.

All the process is transparent and the entries are created when save is called.

You will not have to modify FieldTranslation, but you can read the code.

All code in in the github repository:



This application depends on django-cuser and TinyMCE, so you will need to install it and put it in the list of INSTALLED_APPS before modeltranslation.

You are encouraged to use pip to install django-cuser.

The easiest way to install modeltranslation is by installing it from pipy:

pip install modeltranslation

Once you’ve done this, you can install modeltranslation in

INSTALLED_APPS = ( “tinymce”, “cuser”, “modeltranslation” )


You’ll have to include a new setting in IS_MONOLINGUAL=False. IS_MONOLINGUAL acts as a switch for modeltranslation:

# modeltranslation only works when IS_MONOLINGUAL is False


Add file setting TRANSLATABLE_MODEL_MODULES to TRANSLATABLE_MODEL_MODULES contains a list of module paths that will be translated. For example:

TRANSLATABLE_MODEL_MODULES = ["app1.models", "app2.models", "fees.models", "menus.models", ...]

Import addtranslations

Import addtranslations if each of your files:

from modeltranslation.translation import addtranslations

After that, you’ll have to call addtranslations at the end of this file:


This call adds an observer that saves translations when save model method is executed.

Add translatable_fields to your models

Modify your models including a meta field “translatable_fields”. This field is a list with the fields you want to translate.

For example:

from django.db import models

class Event(models.Model):

    name = models.CharField(blank=False, max_length=150, verbose_name=u"Name", help_text=u"Name of the event.")
    description = models.TextField(blank=False, verbose_name=u"Description", help_text=u"Long description of the event.")
    short_description = models.CharField(blank=False, max_length=150, verbose_name=u"Short description", help_text=u"Short description of the event.")


    ## Event Meta
    class Meta:
        verbose_name = "event"
        verbose_name_plural = "events"
        translatable_fields = ("name", "description", "short_description")

And that’s all!

Now you have everything configurated and can use modeltranslation translations.

How to use translations in ModelForms

Make your ModelForm object inherits of TranslatableModelForm. This will include automatically the extra fields for each language you have in your website.

from modeltranslation.forms import TranslatableModelForm

class EventForm(TranslatableModelForm):

If you need to modify any of the fields in init method (for example by changing the widget of one field), you’ll have to call _add_translation_form_fields after your changes.

For example:

# EventForm __init__
def __init__(self, event, *args, **kwargs):
    super(EventForm, self).__init__(*args, **kwargs)

    # Adds TinyMCE editor but we also want this editor in other
    # languages' description fields
    self.fields["description"].widget = TinyMCE()

    # Manually adition of translation fields

Dynamic translations in Django templates

  1. Include modeltranslation filters in each template you wan to use this special filters.

{% load modeltranslation_tags %}
  1. Use filter “_” with the object and one of its fields. This filter will return the translation of that field in the current language.

For example:

{{ event|_:"name" }} {# Translates event name #}
{{ event.area|_:"name" }} {# Translates area name #}

Dynamic translations in code

This application injects a new method to each translatable model: get_trans_attr. This method returns the translation of the attribute in the current language (if it exists), otherwise returns the default value for this attribute:

For example:

# Original event name

# Translated event name
translated_event_name event.get_trans_attr("name")

Contact and suggestions

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modeltranslation-0.25.tar.gz (5.1 MB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page