Page structure

Wagtail stores content in a separate page tree for each locale.

For example, if you have two sites in two locales, then you will see four homepages at the top level of the page hierarchy in the explorer.

This approach has some advantages for the editor experience as well:

• There is no default language for editing, so content can be authored in any language and then translated to any other.
• Translations of a page are separate pages so they can be published at different times.
• Editors can be given permission to edit content in one locale and not others.

How locales and translations are recorded in the database

All pages (and any snippets that have translation enabled) have a locale and translation_key field:

• locale is a foreign key to the Locale model
• translation_key is a UUID that’s used to find translations of a piece of content. Translations of the same page/snippet share the same value in this field

These two fields have a ‘unique together’ constraint so you can’t have more than one translation in the same locale.

Translated homepages

When you set up a site in Wagtail, you select the site’s homepage in the ‘root page’ field and all requests to that site’s root URL will be routed to that page.

Multi-lingual sites have a separate homepage for each locale that exist as siblings in the page tree. Wagtail finds the other homepages by looking for translations of the site’s ‘root page’.

This means that to make a site available in another locale, you just need to translate and publish its homepage in that new locale.

If Wagtail can’t find a homepage that matches the user’s language, it will fall back to the page that is selected as the ‘root page’ on the site record, so you can use this field to specify the default language of your site.

Language detection and routing

For detecting the user’s language and adding a prefix to the URLs (/en/, /fr-fr/, for example), Wagtail is designed to work with Django’s built-in internationalisation utilities such as i18n_patterns and LocaleMiddleware. This means that Wagtail should work seamlessly with any other internationalised Django applications on your site.

Locales

The locales that are enabled on a site are recorded in the Locale model in wagtailcore. This model has just two fields: ID and language_code which stores the BCP-47 language tag that represents this locale.

The locale records can be set up with an optional management UI or created in the shell. The possible values of the language_code field are controlled by the WAGTAIL_CONTENT_LANGUAGES setting.

Enabling internationalisation

To enable internationalisation in both Django and Wagtail, set the following settings to True:

# my_project/settings.py

USE_I18N = True
WAGTAIL_I18N_ENABLED = True

In addition, you might also want to enable Django’s localisation support. This will make dates and numbers display in the user’s local format:

# my_project/settings.py

USE_L10N = True

Configuring available languages

Next we need to configure the available languages. There are two settings for this that are each used for different purposes:

• LANGUAGES - This sets which languages are available on the frontend of the site.
• WAGTAIL_CONTENT_LANGUAGES - This sets which the languages Wagtail content can be authored in.

You can set both of these settings to the exact same value. For example, to enable English, French, and Spanish:

# my_project/settings.py

WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [
    ('en', "English"),
    ('fr', "French"),
    ('es', "Spanish"),
]

You can also set these to different values. You might want to do this if you want to have some programmatic localisation (like date formatting or currency, for example) but use the same Wagtail content in multiple regions:

# my_project/settings.py

LANGUAGES = [
    ('en-GB', "English (Great Britain)"),
    ('en-US', "English (United States)"),
    ('en-CA', "English (Canada)"),
    ('fr-FR', "French (France)"),
    ('fr-CA', "French (Canada)"),
]

WAGTAIL_CONTENT_LANGUAGES = [
    ('en-GB', "English"),
    ('fr-FR', "French"),
]

When configured like this, the site will be available in all the different locales in the first list, but there will only be two language trees in Wagtail.

All the en- locales will use the “English” language tree, and the fr- locales will use the “French” language tree. The differences between each locale in a language would be programmatic. For example: which date/number format to use, and what currency to display prices in.

Enabling the locale management UI (optional)

An optional locale management app exists to allow a Wagtail administrator to set up the locales from the Wagtail admin interface.

To enable it, add wagtail.locales into INSTALLED_APPS:

# my_project/settings.py

INSTALLED_APPS = [
    # ...
    'wagtail.locales',
    # ...
]

Adding a language prefix to URLs

To allow all of the page trees to be served at the same domain, we need to add a URL prefix for each language.

To implement this, we can use Django’s built-in i18n_patterns function, which adds a language prefix to all of the URL patterns passed into it. This activates the language code specified in the URL and Wagtail takes this into account when it decides how to route the request.

In your project’s urls.py add Wagtail’s core URLs (and any other URLs you want to be translated) into an i18n_patterns block:

# /my_project/urls.py

# ...

from django.conf.urls.i18n import i18n_patterns

# Non-translatable URLs
# Note: if you are using the Wagtail API or sitemaps,
# these should not be added to `i18n_patterns` either
urlpatterns = [
    path('django-admin/', admin.site.urls),

    path('admin/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),
]

# Translatable URLs
# These will be available under a language code prefix. For example /en/search/
urlpatterns += i18n_patterns(
    path('search/', search_views.search, name='search'),
    path("", include(wagtail_urls)),
)

# myproject/settings.py

# ...

LANGUAGE_CODE = 'en'
WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [
    ('en', "English"),
    ('fr', "French"),
]

# ...

# myproject/urls.py
# ...

# These URLs will be available under a language code prefix only for languages that
# are not set as default in LANGUAGE_CODE.

urlpatterns += i18n_patterns(
    path('search/', search_views.search, name='search'),
    path("", include(wagtail_urls)),
    prefix_default_language=False,
)

- /search/
- /fr/search/

User language auto-detection

After wrapping your URL patterns with i18n_patterns, your site will now respond on URL prefixes. But now it won’t respond on the root path.

To fix this, we need to detect the user’s browser language and redirect them to the best language prefix. The recommended approach to do this is with Django’s LocaleMiddleware:

# my_project/settings.py

MIDDLEWARE = [
    # ...
    'django.middleware.locale.LocaleMiddleware',
    # ...
]

Custom routing/language detection

You don’t strictly have to use i18n_patterns or LocaleMiddleware for this and you can write your own logic if you need to.

All Wagtail needs is the language to be activated (using Django’s django.utils.translation.activate function) before the wagtail.views.serve view is called.

Language/region selector

Perhaps the most important bit of internationalisation-related UI you can add to your site is a selector to allow users to switch between different languages.

If you’re not convinced that you need this, have a look at https://www.w3.org/International/questions/qa-site-conneg#yyyshortcomings for some rationale.

{# make sure these are at the top of the file #}
{% load i18n wagtailcore_tags %}

{% if page %}
    {% for translation in page.get_translations.live %}
        {% get_language_info for translation.locale.language_code as lang %}
        <a href="{% pageurl translation %}" rel="alternate" hreflang="{{ language_code }}">
            {{ lang.name_local }}
        </a>
    {% endfor %}
{% endif %}

{% if page %}
    ...
{% endif %}

{% for translation in page.get_translations.live %}
    ...
{% endfor %}

{% get_language_info for translation.locale.language_code as lang %}

<a href="{% pageurl translation %}" rel="alternate" hreflang="{{ language_code }}">
    {{ lang.name_local }}
</a>

# myproject/settings.py

TEMPLATES = [
    {
        # ...
        'OPTIONS': {
            'context_processors': [
                # ...
                'django.template.context_processors.i18n',
            ],
        },
    },
]

{% for language_code, language_name in LANGUAGES %}
    {% get_language_info for language_code as lang %}

    {% language language_code %}
        <a href="{% pageurl page.localized %}" rel="alternate" hreflang="{{ language_code }}">
            {{ lang.name_local }}
        </a>
    {% endlanguage %}
{% endfor %}

{% for language_code, language_name in LANGUAGES %}
    ...
{% endfor %}

{% get_language_info for language_code as lang %}

{% language language_code %}
    ...
{% endlanguage %}

<a href="{% pageurl page.localized %}" rel="alternate" hreflang="{{ language_code }}">
    {{ lang.name_local }}
</a>

API filters for headless sites

For headless sites, the Wagtail API supports two extra filters for internationalised sites:

• ?locale= Filters pages by the given locale
• ?translation_of= Filters pages to only include translations of the given page ID

For more information, see Special filters for internationalized sites.

Translatable snippets

You can make a snippet translatable by making it inherit from wagtail.models.TranslatableMixin. For example:

# myapp/models.py

from django.db import models

from wagtail.models import TranslatableMixin
from wagtail.snippets.models import register_snippet


@register_snippet
class Advert(TranslatableMixin, models.Model):
    name = models.CharField(max_length=255)

The TranslatableMixin model adds the locale and translation_key fields to the model.

# myapp/models.py

from django.db import models

from wagtail.models import BootstrapTranslatableMixin
from wagtail.snippets.models import register_snippet


@register_snippet
class Advert(BootstrapTranslatableMixin, models.Model):
    name = models.CharField(max_length=255)

    # if the model has a Meta class, ensure it inherits from
    # BootstrapTranslatableMixin.Meta too
    class Meta(BootstrapTranslatableMixin.Meta):
        verbose_name = 'adverts'

python manage.py makemigrations myapp --empty

from django.db import migrations
from wagtail.models import BootstrapTranslatableModel

class Migration(migrations.Migration):
    dependencies = [
        ('myapp', '0002_bootstraptranslations'),
    ]

    # Add one operation for each model to bootstrap here
    # Note: Only include models that are in the same app!
    operations = [
        BootstrapTranslatableModel('myapp.Advert'),
    ]

# myapp/models.py

from wagtail.models import TranslatableMixin  # Change this line

@register_snippet
class Advert(TranslatableMixin, models.Model):  # Change this line
    name = models.CharField(max_length=255)

    class Meta(TranslatableMixin.Meta):  # Change this line, if present
        verbose_name = 'adverts'

python manage.py makemigrations myapp
python manage.py migrate

Wagtail Localize

As part of the initial work on implementing internationalisation for Wagtail core, we also created a translation package called wagtail-localize. This supports translating pages within Wagtail, using PO files, machine translation, and external integration with translation services.

Github: https://github.com/wagtail/wagtail-localize