Models¶
Defining models¶
Models which have fields that should be translatable have to inherit
hvad.models.TranslatableModel
instead of
django.db.models.Model
. Their default manager (usually the objects
attribute) must be an instance of hvad.manager.TranslationManager
or a
subclass of that class. Your inner Meta
class on the model may not
use any translated fields in it’s options.
Fields to be translated have to be wrapped in a
hvad.models.TranslatedFields
instance which has to be assigned to an
attribute on your model. That attribute will be the reversed ForeignKey from the
Translations Model to your Shared Model.
If you want to customize your Translations Model using directives on a
inner Meta
class, you can do so by passing a dictionary holding the
directives as the meta
keyword to hvad.models.TranslatedFields
.
A full example of a model with translations:
from django.db import models
from hvad.models import TranslatableModel, TranslatedFields
class TVSeries(TranslatableModel):
distributor = models.CharField(max_length=255)
translations = TranslatedFields(
title = models.CharField(max_length=100),
subtitle = models.CharField(max_length=255),
released = models.DateTimeField(),
meta={'unique_together': [('title', 'subtitle')]},
)
New methods¶
translate¶
-
translate
(language_code) Returns this model instance for the language specified.
Warning
This does not check if this language already exists in the database and assumes it doesn’t! If it already exists and you try to save this instance, it will break!
Note
This method does not perform any database queries.
safe_translation_getter¶
-
safe_translation_getter
(name, default=None)¶ Returns the value of the field specified by
name
if it’s available on this instance in the currently cached language. It does not try to get the value from the database. Returns the value specified indefault
if no translation was cached on this instance or the translation does not have a value for this field.This method is useful to safely get a value in methods such as
__unicode__()
.Note
This method does not perform any database queries.
Example usage:
class MyModel(TranslatableModel):
translations = TranslatedFields(
name = models.CharField(max_length=255)
)
def __unicode__(self):
return self.safe_translation_getter('name', 'MyMode: %s' % self.pk)
-
lazy_translation_getter
(name, default=None)¶ Returns the value of the field specified by
name
even thought it’s not available on this instance in the currently cached language. Returns the value specified indefault
if no translation available on this instance or the translation does not have a value for this field.This method is useful to get a value in methods such as
__unicode__()
.Note
This method may perform database queries.
Example usage:
class MyModel(TranslatableModel):
translations = TranslatedFields(
name = models.CharField(max_length=255)
)
def __unicode__(self):
return self.lazy_translation_getter('name', 'MyMode: %s' % self.pk)
Changed methods¶
save¶
-
save
(force_insert=False, force_update=False, using=None) This method runs an extra query when used to save the translation cached on this instance, if any translation was cached.
Working with relations¶
Foreign keys pointing to a Translated Model always point to the Shared Model. It is currently not possible to have a foreign key to a Translations Model.
Please note that django.db.models.query.QuerySet.select_related()
used on
a foreign key pointing to a Translated Model does not span to its
Translations Model and therefore accessing a translated field over the
relation causes an extra query.
If you wish to filter over a translated field over the relation from a
Normal Model you have to use
hvad.utils.get_translation_aware_manager()
to get a manager that allows
you to do so. That function takes your model class as argument and returns a
manager that works with translated fields on related models.