Quickstart

Define a multilingual model

Defining a multilingual model is very similar to defining a normal Django model, with the difference that instead of subclassing django.db.models.Model you have to subclass hvad.models.TranslatableModel and that all fields which should be translatable have to be wrapped inside a hvad.models.TranslatedFields.

Let’s write an easy model which describes Django applications with translatable descriptions and information about who wrote the description:

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


class DjangoApplication(TranslatableModel):
    name = models.CharField(max_length=255, unique=True)
    author = models.CharField(max_length=255)

    translations = TranslatedFields(
        description = models.TextField(),
        description_author = models.CharField(max_length=255),
    )

    def __unicode__(self):
        return self.name

The fields name and author will not get translated, the fields description and description_author will.

Using multilingual models

Now that we have defined our model, let’s play around with it a bit. The following code examples are taken from a Python shell.

Import our model:

>>> from myapp.models import DjangoApplication

Create an untranslated instance:

>>> hvad = DjangoApplication.objects.create(name='django-hvad', author='Jonas Obrist')
>>> hvad.name
'django-hvad'
>>> hvad.author
'Jonas Obrist'

Turn the untranslated instance into a translated instance with the language 'en' (English):

>>> hvad.translate('en')
<DjangoApplication: django-hvad>

Set some translated fields and save the instance:

>>> hvad.description = 'A project to do multilingual models in Django'
>>> hvad.description_author = 'Jonas Obrist'
>>> hvad.save()

Get the instance again and check that the fields are correct:

>>> obj = DjangoApplication.objects.language('en').get(name='django-hvad')
>>> obj.name
u'django-hvad'
>>> obj.author
u'Jonas Obrist'
>>> obj.description
u'A project to do multilingual models in Django'
>>> obj.description_author
u'Jonas Obrist'

Note

I use hvad.manager.TranslationQueryset.language() here because I’m in an interactive shell, which is not necessarily in English, in your normal views, you can usually omit the call to that method, since the environment should already be in a valid language when in a request/response cycle.

Let’s get all Django applications which have a description written by 'Jonas Obrist' (in English):

>>> DjangoApplication.objects.language('en').filter(description_author='Jonas Obrist')
[<DjangoApplication: django-hvad>]