wagtail-localize

1.13 verified Fri May 01 auth: no python

Translation plugin for Wagtail CMS. Automates translation of Wagtail pages, snippets, and content by syncing translatable fields to a separate locale model. Current version: 1.13 (2025-05-22). Supports Wagtail 7.x, Django 6.0, Python >=3.10. Release cadence: ~3 minor versions per year.

pip install wagtail-localize

Common errors

error 'module' object has no attribute 'Locale' ↓

cause Importing Locale from wagtail.models or wrong path.

fix

Use: from wagtail_localize.models import Locale

error ValueError: The locale 'fr' is not in the database. ↓

cause Locale not created before submitting translation.

fix

Ensure locale exists: Locale.objects.get_or_create(language_code='fr')

error django.core.management.base.CommandError: No translation manager for 'wagtail_localize' ↓

cause Missing 'wagtail_localize' in INSTALLED_APPS before running migrate.

fix

Add 'wagtail_localize' to INSTALLED_APPS and run 'manage.py migrate'.

Warnings

breaking In v1.12, support for Wagtail < 6.3 was dropped. If upgrading from <1.12, ensure Wagtail >=6.3. ↓

fix Upgrade Wagtail to >=6.3 before upgrading wagtail-localize.

deprecated The `wagtail_localize.locales` app was split out. In v1.13 it's optional but recommended for locale management UI. Old installations with 'wagtail_localize' only will still work, but new features require the locales app. ↓

fix Add 'wagtail_localize.locales' to INSTALLED_APPS.

gotcha Using `Locale` from `wagtail.models` instead of `wagtail_localize.models` causes confusion. The wagtail-localize `Locale` model is a proxy with extra methods. ↓

fix Always import Locale from wagtail_localize.models.

gotcha Machine translation services (DeepL, LibreTranslate) require explicit configuration. DeepL API changed in v1.12.2: now passes auth key via headers, not query parameters. ↓

fix For DeepL, ensure you are using the new header-based auth: set DEEPL_AUTH_KEY in settings and use DeepLBackend.

gotcha `submit_translations` is a synchronous helper and will block if `submit_synchronously=True`. In production, use Celery or a task queue for async submission. ↓

fix For async, use `submit_translations.delay()` (requires a Celery setup).

Imports

Locale
wrong
```
from wagtail.models import Locale
```
correct
```
from wagtail_localize.models import Locale
```
wagtail's own Locale model is not the same; wagtail-localize overrides it

TranslatableMixin

from wagtail_localize.models import TranslatableMixin

StringNotInUseError

from wagtail_localize.models import StringNotInUseError

submit_translations

wrong

from wagtail_localize.views import submit_translations

correct

from wagtail_localize.tasks import submit_translations

not a view; it's a background task

Quickstart

Minimal setup: add app, run migrations, submit a page for translation.

# Add to INSTALLED_APPS in settings.py:
INSTALLED_APPS = [
    ...
    'wagtail_localize',
    'wagtail_localize.locales',  # optional, for locale management UI
]

# Run migrations
# ./manage.py migrate

# In a model that should be translatable:
from wagtail.models import Page
from wagtail_localize.models import TranslatableMixin

class MyPage(Page):
    pass  # Page already inherits TranslatableMixin via wagtail-localize

# Create a locale (if not using wagtail's built-in locales)
from wagtail_localize.models import Locale
locale = Locale.objects.get_or_create(language_code='fr')

# Submit a page for translation
from wagtail_localize.tasks import submit_translations
submit_translations(page.pk, [locale.pk], submit_synchronously=True)