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 parler.models import TranslatableModel, TranslatedFields


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 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)

The TranslatedFieldsModelBase metaclass

class parler.models.TranslatedFieldsModelBase(name, bases, attrs)

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.