parler.models module

The models and fields for translation support.

The default is to use the TranslatedFields class in the model, like:

from django.db import models
from django.utils.encoding import python_2_unicode_compatible
from parler.models import TranslatableModel, TranslatedFields


@python_2_unicode_compatible
class MyModel(TranslatableModel):
    translations = TranslatedFields(
        title = models.CharField(_("Title"), max_length=200)
    )

    class Meta:
        verbose_name = _("MyModel")

    def __str__(self):
        return self.title

It’s also possible to create the translated fields model manually:

from django.db import models
from django.utils.encoding import python_2_unicode_compatible
from parler.models import TranslatableModel, TranslatedFieldsModel
from parler.fields import TranslatedField


class MyModel(TranslatableModel):
    title = TranslatedField()  # Optional, explicitly mention the field

    class Meta:
        verbose_name = _("MyModel")

    def __str__(self):
        return self.title


class MyModelTranslation(TranslatedFieldsModel):
    master = models.ForeignKey(MyModel, related_name='translations', null=True)
    title = models.CharField(_("Title"), max_length=200)

    class Meta:
        verbose_name = _("MyModel translation")

This has the same effect, but also allows to to override the save() method, or add new methods yourself.

The translated model is compatible with django-hvad, making the transition between both projects relatively easy. The manager and queryset objects of django-parler can work together with django-mptt and django-polymorphic.

The TranslatableModel model

class parler.models.TranslatableModel(*args, **kwargs)

Base model class to handle translations.

All translatable fields will appear on this model, proxying the calls to the TranslatedFieldsModel.

The TranslatedFields class

class parler.models.TranslatedFields(meta=None, **fields)

Wrapper class to define translated fields on a model.

The field name becomes the related name of the TranslatedFieldsModel subclass.

Example:

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

class MyModel(TranslatableModel):
    translations = TranslatedFields(
        title = models.CharField("Title", max_length=200)
    )

When the class is initialized, the attribute will point to a ForeignRelatedObjectsDescriptor object. Hence, accessing MyModel.translations.related.related_model returns the original model via the django.db.models.related.RelatedObject class.

Parameters:meta

A dictionary of Meta options, passed to the TranslatedFieldsModel instance.

Example:

class MyModel(TranslatableModel):
    translations = TranslatedFields(
        title = models.CharField("Title", max_length=200),
        slug = models.SlugField("Slug"),
        meta = {'unique_together': [('language_code', 'slug')]},
    )

The TranslatedFieldsModel model

class parler.models.TranslatedFieldsModel(*args, **kwargs)

Base class for the model that holds the translated fields.

classmethod contribute_translations(shared_model)

Add the proxy attributes to the shared model.

is_empty

True when there are no translated fields.

is_modified

Tell whether the object content is modified since fetching it.

master = None

The mandatory Foreign key field to the shared model.

related_name

Returns the related name that this model is known at in the shared model.

shared_model

Returns the shared model this model is linked to.

The TranslatedFieldsModelBase metaclass

class parler.models.TranslatedFieldsModelBase

Meta-class for the translated fields model.

It performs the following steps:

  • It validates the ‘master’ field, in case it’s added manually.
  • It tells the original model to use this model for translations.
  • It adds the proxy attributes to the shared model.

The TranslationDoesNotExist exception

class parler.models.TranslationDoesNotExist

A tagging interface to detect missing translations. The exception inherits from AttributeError to reflect what is actually happening. Therefore it also causes the templates to handle the missing attributes silently, which is very useful in the admin for example. The exception also inherits from ObjectDoesNotExist, so any code that checks for this can deal with missing translations out of the box.

This class is also used in the DoesNotExist object on the translated model, which inherits from:

  • this class
  • the sharedmodel.DoesNotExist class
  • the original translatedmodel.DoesNotExist class.

This makes sure that the regular code flow is decently handled by existing exception handlers.