Skip to main content

Translates Wagtail CMS models using a registration approach.

Project description

Wagtail Modeltranslation

This app is built using core features of django-modeltranslation:

It’s an alternative approach for i18n support on Wagtail CMS websites.

The wagtail-modeltranslation application is used to translate dynamic content of existing Wagtail models to an arbitrary number of languages, without having to change the original model classes. It uses a registration approach (comparable to Django’s admin app) to add translations to existing or new projects and is fully integrated into the Wagtail admin UI.

The advantage of a registration approach is the ability to add translations to models on a per-app basis. You can use the same app in different projects, whether or not they use translations, and without touching the original model class.


  • Add translations without changing existing models or views

  • Translation fields are stored in the same table (no expensive joins)

  • Supports inherited models (abstract and multi-table inheritance)

  • Handle more than just text fields

  • Wagtail admin integration

  • Flexible fallbacks, auto-population and more!

  • Default Page model fields has translatable fields by default

  • StreamFields are now supported!


wagtail-modeltranslation patches Wagtail’s Page model with translation fields title_xx, slug_xx, seo_title_xx, search_description_xx and url_path_xx where “xx” represents the language code for each translated language. This is done without migrations through command sync_page_translation_fields. Since Page model belongs to Wagtail it’s within the realm of possibility that one day Wagtail may add a conflicting field to Page thus interfering with wagtail-modeltranslation.

Wagtail’s slugurl tag does not work across languages. wagtail-modeltranslation provides a drop-in replacement named slugurl_trans which by default takes the slug parameter in the default language.

Quick start

  1. Install wagtail-modeltranslation:

    pip install wagtail-modeltranslation
  2. Add ‘wagtail_modeltranslation’ to your INSTALLED_APPS setting like this (before all apps that you want to translate):

  3. Add ‘django.middleware.locale.LocaleMiddleware’ to MIDDLEWARE on your

        'django.middleware.locale.LocaleMiddleware',  # should be after SessionMiddleware and before CommonMiddleware
  4. Enable i18n on

    USE_I18N = True
  5. Define available languages on

    from django.utils.translation import gettext_lazy as _
        ('pt', _('Portuguese')),
        ('es', _('Spanish')),
        ('fr', _('French')),
  6. Create inside the root folder of the app where the model you want to translate exists:

    from .models import Foo
    from modeltranslation.translator import TranslationOptions
    from modeltranslation.decorators import register
    class FooTR(TranslationOptions):
        fields = (
  7. Run python makemigrations followed by python migrate (repeat every time you add a new language or register a new model)

  8. Run python sync_page_translation_fields (repeat every time you add a new language)

  9. If you’re adding wagtail-modeltranslation to an existing site run python update_translation_fields

Supported versions


wagtail-modeltranslation release

Compatible Wagtail versions

Compatible Django versions

Compatible Python versions


>= 1.12, < 2.12

>= 1.11

2.7, 3.4, 3.5, 3.6


>= 2.13, < 3.0

>= 3.0

3.6, 3.7, 3.8, 3.9


>= 3.0, < 4.0

>= 3.2

3.7, 3.8, 3.9, 3.10


>= 4.0, < 5.0

>= 3.2

3.7, 3.8, 3.9, 3.10


>= 5.0

>= 3.2

3.8, 3.9, 3.10, 3.11

Upgrade considerations (v0.10.8)

  • Template tag change_lang now needs a second parameter, page

Upgrade considerations (v0.8)

This version includes breaking changes as some key parts of the app have been re-written:

  • The most important change is that Page is now patched with translation fields.


To upgrade to this version you need to:

  • Replace the WagtailTranslationOptions with TranslationOptions in all files

  • Run python sync_page_translation_fields at least once to create Page’s translation fields

  • Replace any usages of Wagtail’s {% slugurl ... %} for wagtail-modeltranslation’s own {% slugurl_trans ... %}

  • While optional it’s recommended to add 'wagtail_modeltranslation.makemigrations' to your INSTALLED_APPS. This will override Django’s makemigrations command to avoid creating spurious Page migrations.

Upgrade considerations (v0.6)

This version has some important changes as there was a refactoring to include django-modeltranslation as a dependency instead of duplicating their code in our version. This allow us to focus on Wagtail admin integration features as django-modeltranslation is very well mantained and is very quickly to fix problems with the latest Django versions. This way we also keep all the django-modeltranslation features (if you want you can also customize django-admin, for example). We also provide a new class to create the translation options classes: WagtailTranslationOptions Most of the changes are related to imports as they change from wagtail-modeltranslation to modeltranslation.

To upgrade to this version you need to:

  • Replace the TranslationOptions with WagtailTranslationOptions in all files

  • The import of the register decorator is now from modeltranslation.decorators import register

  • The import of translator is now from modeltranslation.translator import translator

Project Home


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wagtail_modeltranslation-0.14.1.tar.gz (51.6 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page