Features

• Simple - only 3 new queryset methods.

• Natural - use Django ORM as usual, it just became language aware.

• Fast - no additional queries for reads, just an inner join to an indexed key.

• Complete - relationships, custom managers and querysets, proxy models, and abstract models.

• Batteries included - translation-enabled forms and admin are provided.

• Reliable - more than 300 test cases and counting.

• Compatible - follows Django compatibility matrix.

Django-hvad also features support for Django REST framework 3.1 or newer, including translation-aware serializers.

Example Uses

Declaring a translatable Book model:

class Book(TranslatableModel):
    author = models.ForeignKey(Author)
    release = models.Date()

    translations = TranslatedFields(
        title = models.CharField(max_length=250)
    )

Thus, only the title will vary based on the language. Release date and author are shared among all languages. Let’s now create a Book instance:

# The recommended way:
book = Book.objects.language('en').create(
    author = Author.objects.get(name='Antoine de Saint Exupéry'),
    release = datetime.date(1943, 4, 6),
    title = "The Little Prince",
)

# Also works
book = Book(language_code='en')
book.author = Author.objects.get(name='Antoine de Saint Exupéry')
book.release = datetime.date(1943, 4, 6)
book.title = "The Little Prince"
book.save()

Providing some translations:

book.translate('fr')
book.title = "Le Petit Prince"
book.save()
book.translate('de')
book.title = "Der kleine Prinz"
book.save()

Every call to translate() creates a new translation from scratch and switches to that translation; save() only saves the latest translation. Let’s now perform some language-aware queries:

Book.objects.all()

Compatible by default: returns all objects, without any translated fields attached. Starting from v1.0, default behavior can be overriden to work like next query:

Book.objects.language().all()

Returns all objects as translated instances, but only the ones that are translated into the currect language. You can also specify which language to get, using e.g.:

Book.objects.language("en").all()

Usual queryset methods work like they always did: let’s get all books as translated instances, filtering on the title attribute, returning those that have Petit Prince in their French title, ordered by publication date (in their French edition):

Book.objects.language("fr").filter(title__contains='Petit Prince').order_by('release')

Other random examples:

# last German book published in year 1948
Book.objects.language("de").filter(release__year=1948).latest()

# other books from the same author as mybook. Cache author as well.
Book.objects.language().select_related('author').filter(author__books=mybook)

# books that have "Django" in their title, regardless of the language
Book.objects.language('all').filter(title__icontains='Django')

More examples in the quickstart guide.

Releases

Django-hvad uses the same release pattern as Django. The following versions are thus available:

• Legacy branch 1.8, available through PyPI and git branch releases/1.8.x.

• Stable branch 2.0, available through PyPI and git branch releases/2.0.x.

• Development branch 2.1, available through git branch master.

Stable branches have minor bugfix releases as needed, with guaranteed compatibility. See the installation guide for details, or have a look at the release notes.

Thanks to

Jonas Obrist (https://github.com/ojii) for making django-nani and for helping me with this project.

Kristian Øllegaard (https://github.com/KristianOellegaard/) for django-hvad and trusting me to continue the development.