Getting started

To start using wagtailtrans in your project, take the following steps:


  1. Install Wagtailtrans via pip
$ pip install wagtailtrans
  1. Add wagtailtrans and wagtail.contrib.modeladmin to your INSTALLED_APPS:
    # ...
    # ...


As of Wagtailtrans 1.0.3 the custom Language management views are replaced with with wagtail.contrib.modeladmin This needs to be added to INSTALLED_APPS as well.

  1. Add wagtailtrans.middleware.TranslationMiddleware to your MIDDLEWARE_CLASSES:
    # ...
    # ...


Keep in mind wagtailtrans.middleware.TranslationMiddleware is a replacement for django.middleware.locale.LocaleMiddleware.


It relies on wagtail.wagtailcore.middleware.SiteMiddleware, which should come before it. See for more information.

  1. Optionally, add WAGTAILTRANS_TEMPLATE_DIR to your TEMPLATES[0]['DIRS']


As of Wagtail 1.8 Page.get_admin_display_title is added which doesn’t require overriding admin templates anymore, so if you’re on Wagtail >= 1.8 you can skip this step.

from wagtailtrans import WAGTAILTRANS_TEMPLATE_DIR

    # ...
    'DIRS': [
    # ...


Before we start incorporating wagtailtrans in your project, you’ll need to configure wagtailtrans for the behavior that best suits the need of your project. The required settings to consider here are:


Both settings are mandatory but provided with a default value, so if you want synchronized trees and no languages per site, you’re good to go from here.

See also

Complete reference about available settings: Settings


To start using wagtailtrans we first need to create a translation home page. This page will route the requests to the homepage in the right language. We can create a translation site root page by creating the wagtailtrans.models.TranslatableSiteRootPage as the first page under the root page.

In this example we will also make a HomePage which will be translatable. This is done by implementing the wagtailtrans.models.TranslatablePage next to Wagtail’s Page

from wagtail.wagtailcore.models import Page
from wagtailtrans.models import TranslatablePage

class HomePage(TranslatablePage, Page):
    body = RichTextField(blank=True, default="")
    image = models.ForeignKey('wagtailimages.Image', null=True, blank=True, on_delete=models.SET_NULL, related_name='+')

    content_panels = Page.content_panels + [

    subpage_types = [
        # Your subpage types.

This will create our first translatable page. To start using it we first need to migrate our database

$ python makemigrations
$ python migrate

Now run the server and under the page Root create a TranslatableSiteRootPage (MySite).

Next we need to create a site and point it’s root_page to our TranslatableSiteRootPage (MySite).

Create your site and select ``MySite`` as root page.

We now have the basics for a Translatable Site.