{"id":24820,"library":"wagtail-localize","title":"wagtail-localize","description":"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.","status":"active","version":"1.13","language":"python","source_language":"en","source_url":"https://github.com/wagtail/wagtail-localize","tags":["wagtail","translation","i18n","localization","django"],"install":[{"cmd":"pip install wagtail-localize","lang":"bash","label":"PyPI install"}],"dependencies":[{"reason":"Core dependency; wagtail-localize is a plugin for Wagtail CMS","package":"wagtail","optional":false}],"imports":[{"note":"wagtail's own Locale model is not the same; wagtail-localize overrides it","wrong":"from wagtail.models import Locale","symbol":"Locale","correct":"from wagtail_localize.models import Locale"},{"note":"","wrong":"","symbol":"TranslatableMixin","correct":"from wagtail_localize.models import TranslatableMixin"},{"symbol":"StringNotInUseError","correct":"from wagtail_localize.models import StringNotInUseError"},{"note":"not a view; it's a background task","wrong":"from wagtail_localize.views import submit_translations","symbol":"submit_translations","correct":"from wagtail_localize.tasks import submit_translations"}],"quickstart":{"code":"# Add to INSTALLED_APPS in settings.py:\nINSTALLED_APPS = [\n    ...\n    'wagtail_localize',\n    'wagtail_localize.locales',  # optional, for locale management UI\n]\n\n# Run migrations\n# ./manage.py migrate\n\n# In a model that should be translatable:\nfrom wagtail.models import Page\nfrom wagtail_localize.models import TranslatableMixin\n\nclass MyPage(Page):\n    pass  # Page already inherits TranslatableMixin via wagtail-localize\n\n# Create a locale (if not using wagtail's built-in locales)\nfrom wagtail_localize.models import Locale\nlocale = Locale.objects.get_or_create(language_code='fr')\n\n# Submit a page for translation\nfrom wagtail_localize.tasks import submit_translations\nsubmit_translations(page.pk, [locale.pk], submit_synchronously=True)","lang":"python","description":"Minimal setup: add app, run migrations, submit a page for translation."},"warnings":[{"fix":"Upgrade Wagtail to >=6.3 before upgrading wagtail-localize.","message":"In v1.12, support for Wagtail < 6.3 was dropped. If upgrading from <1.12, ensure Wagtail >=6.3.","severity":"breaking","affected_versions":">=1.12"},{"fix":"Add 'wagtail_localize.locales' to INSTALLED_APPS.","message":"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.","severity":"deprecated","affected_versions":">=1.13"},{"fix":"Always import Locale from wagtail_localize.models.","message":"Using `Locale` from `wagtail.models` instead of `wagtail_localize.models` causes confusion. The wagtail-localize `Locale` model is a proxy with extra methods.","severity":"gotcha","affected_versions":"all"},{"fix":"For DeepL, ensure you are using the new header-based auth: set DEEPL_AUTH_KEY in settings and use DeepLBackend.","message":"Machine translation services (DeepL, LibreTranslate) require explicit configuration. DeepL API changed in v1.12.2: now passes auth key via headers, not query parameters.","severity":"gotcha","affected_versions":">=1.12.2"},{"fix":"For async, use `submit_translations.delay()` (requires a Celery setup).","message":"`submit_translations` is a synchronous helper and will block if `submit_synchronously=True`. In production, use Celery or a task queue for async submission.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use: from wagtail_localize.models import Locale","cause":"Importing Locale from wagtail.models or wrong path.","error":"'module' object has no attribute 'Locale'"},{"fix":"Ensure locale exists: Locale.objects.get_or_create(language_code='fr')","cause":"Locale not created before submitting translation.","error":"ValueError: The locale 'fr' is not in the database."},{"fix":"Add 'wagtail_localize' to INSTALLED_APPS and run 'manage.py migrate'.","cause":"Missing 'wagtail_localize' in INSTALLED_APPS before running migrate.","error":"django.core.management.base.CommandError: No translation manager for 'wagtail_localize'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}