Wagtail Parler 🧀 🐦

Brings "omelette du fromage" 🧀 from parler into wagtail 🐦 for your custom models (via modeladmin or wagtail snippets)

Wagtail Parler helps you to use django-parler inside wagtail to translate your customs models. It works for wagtail-modeladmin (which is now deprectaed) and also the new official way: wagtail's snippets.

Tests, QA, consistency and compatibility

This app is tested to runs with:

• Django 4.2, 5.2
• Wagtail 5.0, 5.1, 5.2, 6.3, 7.0, 7.1, 7.2
• Parler 2.3 (probably older ones to, it's just not tested)
• Python 3.9, 3.11

To ensure code quality and consistency:

• Formatted with ruff
• Validated with flake8.
• Static types checked with mypy
• Tests coverage checked with coverage (100% tested)
• Tests runned in local via tox and on github via github actions workflow
• versionned with semver logic

Why

There is already an internationalisation support in wagtail via their own language features called wagtail-localize. This app also support wagtail modeladmin. But the approach of wagtail-localize could be unconvenient as translations are stored in the same table than "main instances", resulting specific queryset and managers to manage your models.
For app's like treebeard, it can break the logic of your tree.

For those reasons, you could prefer to use django-parler as translations approach. Wagtail Parler is fit to you: it will allow you to use django-parler to translate your own models and still have a usefull wagtail interface to manage translations (via official wagtail's snippet admin but also with the old wagtail-modeladmin)

Installation

Install the package via pip. We consider you already have django-parler and wagtail installed.

pip install wagtail-parler

Then, in settings.py, add wagtail_parler to the installed apps.

# settings.py

INSTALLED_APPS = [
    # "wagtail.users" # for wagtail >= 7
    # …
    "wagtail_parler",
    # …
]

ATTENTION! Since wagtail 7, you need also to add wagtail.users in the installed app if not already done!

Basic Usage

You just have to add ParlerSnippetAdminMixin to your SnippetViewSet (or ParlerModelAdminMixin to your ModelAdmin), et voilà, you are ready to eat omelette du fromage.

from wagtail.snippets.views.snippets import SnippetViewSet
from wagtail.snippets.models import register_snippet
from wagtail_parler.handlers import ParlerSnippetAdminMixin
from .models import Food


class FoodAdmin(ParlerSnippetAdminMixin, SnippetViewSet):
    model = Food

register_snippet(FoodAdmin)

# or for an usage with wagtail-modeladmin:

from wagtail_modeladmin.options import ModelAdmin, modeladmin_register
from wagtail_parler.handlers import ParlerModelAdminMixin
from .models import Food

class FoodAdmin(ParlerModelAdminMixin, ModelAdmin):
    model = Food

modeladmin_register(FoodAdmin)

Add languages info in the admin

A custom column LanguagesColumn is also available to display languages translations state.

...
from wagtail_parler.admin.columns import LanguagesColumn

class FoodAdmin(ParlerSnippetAdminMixin, SnippetViewSet):
    model = Food
    list_display = [..., LanguagesColumn("translations"), ...]

register_snippet(FoodAdmin)

Doest it support PreviewableMixin ?

Yes it does. When user change the translation tab, preview is updated with translated data from the form. Same behaviour when a data is updated of course.

Doest it support RevisionMixin ?

Yes it does, but you need to inherit from wagtail_parler.models.WagtailParlerModel instead of parler.models.TranslatableModel. eg:

# Django imports
from django.db import models
from django.utils.translation import gettext_lazy as _

# Third Party
from wagtail.models import RevisionMixin
from wagtail_parler.models import WagtailParlerModel
from parler.models import TranslatedFields


class Food(RevisionMixin, WagtailParlerModel):
    slug = models.SlugField(
        verbose_name=_("Slug"),
        blank=False,
        null=False,
    )
    translations = TranslatedFields(
        name=models.CharField(_("Nom"), max_length=255, blank=False, null=False),
        summary=models.TextField(_("Résumé"), blank=False, null=False),
        content=models.TextField(_("Contenu"), blank=False, null=False),
    )

Extra 🧀🐦

More advanced usage, tests, etc., are documented in the doc.

Maître Wagtail, sur un arbre perché,
Tenait en son bec une omelette du fromage.
Maître Webu, à l'envie de parler,
Lui tint à peu près ce langage :
Et bonjour, Monsieur Wagtail.
Que de beaux commits ! quelle merveille !
Sans mentir, si votre codage
Se rapporte à votre plumage,
Vous êtes le Phénix des hôtes de ces dépots. …

From « Le Corbeau et le Renard » by Jean de La Fontaine, 1668.