Install with pip:
pip install wagtail-localize
Add wagtail_localize
and any optional sub modules to INSTALLED_APPS
in settings/base.py
:
INSTALLED_APPS = [
...
"wagtail_localize",
"wagtail_localize.admin.workflow",
"wagtail_localize.translation",
"wagtail_localize.translation.engines.google_translate",
]
Also remove the following from INSTALLED_APPS
:
"wagtail.contrib.redirects",
Add the following to MIDDLEWARE
:
"django.middleware.locale.LocaleMiddleware",
and disable:
"wagtail.contrib.redirects.middleware.RedirectMiddleware",
Ensure your settings file has:
LANGUAGE_CODE = "en-gb" # Or your preferred default language
USE_I18N = True
Add to following to your settings specifying any languages you would like to translate:
LANGUAGES = [
("en", "English"),
("fr", "French"),
]
The following additions need to be made to ./yoursite/urls.py
from django.conf.urls.i18n import i18n_patterns
...
urlpatterns += i18n_patterns(
url(r"^search/$", search_views.search, name="search"),
url(r"", include(wagtail_urls)),
)
Wagtail-localize provides classes wich page models should extend if they are to be translatable. This will be different if you are enabling translation on an existing site with pages, or a new site.
Returns the translation of the page that should be used to route the specified request.
The base class for providing attributes needed to store translation mapping values:
translation_key
- AUUID
that is shared between all translations of the same object/pagelocale
- A foreign key to thewagtail_localize.Locale
table which could represent a language or language/regionis_source_translation
- A boolean field that isTrue
if this object is the translation source for objects with the sametranslation_key
This adds the following methods to the model:
get_translations(inclusive=False)
- Returns aQuerySet
of translations of this object. This object will be excluded from thatQuerySet
unlessinclusive
is set toTrue
get_translation(locale)
- Returns the translated version of the object in that target locale. RaisesModel.DoesNotExist
if the object hasn't been translated into the that target localeget_translation_or_none(locale)
- Similar toget_translation(locale)
except it returnsNone
if the object hasn't been translated into the that target localehas_translation(locale)
- ReturnsTrue
if the object has been translated into the target localecopy_for_translation(locale)
- Makes a copy of the object with thelocale
field of the new object set to the target locale
A specialised version of TranslatableMixin
to be used on page models. It has the following differences:
-
The
copy_for_translation
method will create the new page underneath the translation of the parent page (for example, if a page in the English "News" section is copied for translation into German, the new page will be automatically created under the "Nachrichten" section in the German site tree) -
The
copy
method has been overridden to change thetranslation_key
field. This method is called from the regular page copy action in the admin, it effectively creates a new page so thetranslation_key
needs to be given a new value.
A version of TranslatableMixin
/TranslatablePageMixin
without uniqueness constraints. This is to make it easy to transition existing models to being translatable. This is only used for generating the correct migrations in order to set the translation_key
field uniquely for existing content.
The homepage should extend both TranslatablePageMixin
and TranslatablePageRoutingMixin
from wagtail_localize.models import TranslatablePageMixin, TranslatablePageRoutingMixin
...
class HomePage(TranslatablePageRoutingMixin, TranslatablePageMixin, Page):
Then each page model that requires translation should extend TranslatablePageMixin:
from wagtail_localize.models import TranslatablePageMixin
...
class ArticlePage(TranslatablePageMixin, SocialFields, ListingFields, Page):
The process is as follows:
- Add
BootstrapTranslatableMixin
to your page models - Run
django-admin makemigrations
- Create a data migration for each app, then use the BootstrapTranslatableModel operation in
wagtail_localize.bootstrap
on each model in that app - Change
BootstrapTranslatableMixin
toTranslatableMixin
(orTranslatablePageMixin
, if it's a page model) - Run
django-admin makemigrations
again
wagtail_localize
stores the list of available languages in the database. To populate this to have the same values as is in the LANGUAGES
Django setting, you must run the following command:
python manage.py sync_languages
description of submodules 'wagtail_localize.admin.workflow', 'wagtail_localize.translation', 'wagtail_localize.translation.engines.google_translate',