# 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 = {'constraints': [models.UniqueConstraint(fields=['language_code', 'slug'], name='mymodel_translation_uniq_lang_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.