Wagtail Modeltranslation
========================
This app is built using core features of django-modeltranslation: https://github.com/deschler/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.
.. image:: https://github.com/infoportugal/wagtail-modeltranslation/blob/master/screenshot.png?raw=true
:target: https://github.com/infoportugal/wagtail-modeltranslation/blob/master/screenshot.png?raw=true
Features
========
- 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!
Caveats
=======
:code:`wagtail-modeltranslation` patches Wagtail's :code:`Page` model with translation fields
:code:`title_xx`, :code:`slug_xx`, :code:`seo_title_xx`, :code:`search_description_xx` and :code:`url_path_xx` where "xx" represents the language code for each translated language. This
is done without migrations through command :code:`sync_page_translation_fields`. Since :code:`Page` model belongs to
Wagtail it's within the realm of possibility that one day Wagtail may add a conflicting field to :code:`Page` thus interfering with :code:`wagtail-modeltranslation`.
Wagtail's :code:`slugurl` tag does not work across languages. :code:`wagtail-modeltranslation` provides a drop-in replacement named :code:`slugurl_trans` which by default takes the slug parameter in the default language.
Quick start
===========
1. Install :code:`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)::
INSTALLED_APPS = (
...
'wagtail_modeltranslation',
'wagtail_modeltranslation.makemigrations',
'wagtail_modeltranslation.migrate',
)
3. Add 'django.middleware.locale.LocaleMiddleware' to ``MIDDLEWARE`` on your ``settings.py``::
MIDDLEWARE = (
...
'django.middleware.locale.LocaleMiddleware', # should be after SessionMiddleware and before CommonMiddleware
)
4. Enable i18n on ``settings.py``::
USE_I18N = True
5. Define available languages on ``settings.py``::
from django.utils.translation import gettext_lazy as _
LANGUAGES = (
('pt', _('Portuguese')),
('es', _('Spanish')),
('fr', _('French')),
)
6. Create ``translation.py`` 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
@register(Foo)
class FooTR(TranslationOptions):
fields = (
'body',
)
7. Run :code:`python manage.py makemigrations` followed by :code:`python manage.py migrate` (repeat every time you add a new language or register a new model)
8. Run :code:`python manage.py sync_page_translation_fields` (repeat every time you add a new language)
9. If you're adding :code:`wagtail-modeltranslation` to an existing site run :code:`python manage.py update_translation_fields`
Supported versions
==================
.. list-table:: Title
:widths: 25 25 25 25
:header-rows: 1
* - wagtail-modeltranslation release
- Compatible Wagtail versions
- Compatible Django versions
- Compatible Python versions
* - 0.10
- >= 1.12, < 2.12
- >= 1.11
- 2.7, 3.4, 3.5, 3.6
* - 0.11
- >= 2.13, < 3.0
- >= 3.0
- 3.6, 3.7, 3.8, 3.9
* - 0.12
- >= 3.0, < 4.0
- >= 3.2
- 3.7, 3.8, 3.9, 3.10
* - 0.13
- >= 4.0, < 5.0
- >= 3.2
- 3.7, 3.8, 3.9, 3.10
* - 0.14
- >= 5.0, < 6.0
- >= 3.2
- 3.8, 3.9, 3.10, 3.11
* - 0.15
- >= 5.2
- >= 4.2
- 3.8, 3.9, 3.10, 3.11, 3.12
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.
- ``WAGTAILMODELTRANSLATION_ORIGINAL_SLUG_LANGUAGE`` setting has been deprecated.
To upgrade to this version you need to:
- Replace the ``WagtailTranslationOptions`` with ``TranslationOptions`` in all translation.py files
- Run :code:`python manage.py sync_page_translation_fields` at least once to create ``Page``'s translation fields
- Replace any usages of Wagtail's ``{% slugurl ... %}`` for :code:`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 translation.py 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
------------
https://github.com/infoportugal/wagtail-modeltranslation
Documentation
-------------
http://wagtail-modeltranslation.readthedocs.io/
Raw data
{
"_id": null,
"home_page": "https://github.com/infoportugal/wagtail-modeltranslation",
"name": "wagtail-modeltranslation",
"maintainer": "InfoPortugal S.A.",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "suporte24@infoportugal.pt",
"keywords": "django, wagtail, translation, i18n",
"author": "InfoPortugal S.A.",
"author_email": "suporte24@infoportugal.pt",
"download_url": "https://files.pythonhosted.org/packages/85/57/e6638f908c4a5bc2f022b216c03294693b5773cc6a7d665ba8e08473d2bb/wagtail_modeltranslation-0.15.0.tar.gz",
"platform": null,
"description": "Wagtail Modeltranslation\n========================\n\nThis app is built using core features of django-modeltranslation: https://github.com/deschler/django-modeltranslation\n\nIt's an alternative approach for i18n support on Wagtail CMS websites.\n\nThe wagtail-modeltranslation application is used to translate dynamic content of\nexisting Wagtail models to an arbitrary number of languages, without having to\nchange the original model classes. It uses a registration approach (comparable\nto Django's admin app) to add translations to existing or new projects and is\nfully integrated into the Wagtail admin UI.\n\nThe advantage of a registration approach is the ability to add translations to\nmodels on a per-app basis. You can use the same app in different projects,\nwhether or not they use translations, and without touching the original\nmodel class.\n\n\n.. image:: https://github.com/infoportugal/wagtail-modeltranslation/blob/master/screenshot.png?raw=true\n :target: https://github.com/infoportugal/wagtail-modeltranslation/blob/master/screenshot.png?raw=true\n\n\nFeatures\n========\n\n- Add translations without changing existing models or views\n- Translation fields are stored in the same table (no expensive joins)\n- Supports inherited models (abstract and multi-table inheritance)\n- Handle more than just text fields\n- Wagtail admin integration\n- Flexible fallbacks, auto-population and more!\n- Default Page model fields has translatable fields by default\n- StreamFields are now supported!\n\n\nCaveats\n=======\n\n:code:`wagtail-modeltranslation` patches Wagtail's :code:`Page` model with translation fields\n:code:`title_xx`, :code:`slug_xx`, :code:`seo_title_xx`, :code:`search_description_xx` and :code:`url_path_xx` where \"xx\" represents the language code for each translated language. This\nis done without migrations through command :code:`sync_page_translation_fields`. Since :code:`Page` model belongs to\nWagtail it's within the realm of possibility that one day Wagtail may add a conflicting field to :code:`Page` thus interfering with :code:`wagtail-modeltranslation`.\n\nWagtail's :code:`slugurl` tag does not work across languages. :code:`wagtail-modeltranslation` provides a drop-in replacement named :code:`slugurl_trans` which by default takes the slug parameter in the default language.\n\nQuick start\n===========\n\n1. Install :code:`wagtail-modeltranslation`::\n\n pip install wagtail-modeltranslation\n\n2. Add 'wagtail_modeltranslation' to your ``INSTALLED_APPS`` setting like this (before all apps that you want to translate)::\n\n INSTALLED_APPS = (\n ...\n 'wagtail_modeltranslation',\n 'wagtail_modeltranslation.makemigrations',\n 'wagtail_modeltranslation.migrate',\n )\n\n3. Add 'django.middleware.locale.LocaleMiddleware' to ``MIDDLEWARE`` on your ``settings.py``::\n\n MIDDLEWARE = (\n ...\n 'django.middleware.locale.LocaleMiddleware', # should be after SessionMiddleware and before CommonMiddleware\n )\n\n4. Enable i18n on ``settings.py``::\n\n USE_I18N = True\n\n5. Define available languages on ``settings.py``::\n\n from django.utils.translation import gettext_lazy as _\n\n LANGUAGES = (\n ('pt', _('Portuguese')),\n ('es', _('Spanish')),\n ('fr', _('French')),\n )\n\n6. Create ``translation.py`` inside the root folder of the app where the model you want to translate exists::\n\n from .models import Foo\n from modeltranslation.translator import TranslationOptions\n from modeltranslation.decorators import register\n\n @register(Foo)\n class FooTR(TranslationOptions):\n fields = (\n 'body',\n )\n\n7. Run :code:`python manage.py makemigrations` followed by :code:`python manage.py migrate` (repeat every time you add a new language or register a new model)\n\n8. Run :code:`python manage.py sync_page_translation_fields` (repeat every time you add a new language)\n\n9. If you're adding :code:`wagtail-modeltranslation` to an existing site run :code:`python manage.py update_translation_fields`\n\n\nSupported versions\n==================\n\n.. list-table:: Title\n :widths: 25 25 25 25\n :header-rows: 1\n\n * - wagtail-modeltranslation release\n - Compatible Wagtail versions\n - Compatible Django versions\n - Compatible Python versions\n * - 0.10\n - >= 1.12, < 2.12\n - >= 1.11\n - 2.7, 3.4, 3.5, 3.6\n * - 0.11\n - >= 2.13, < 3.0\n - >= 3.0\n - 3.6, 3.7, 3.8, 3.9\n * - 0.12\n - >= 3.0, < 4.0\n - >= 3.2\n - 3.7, 3.8, 3.9, 3.10\n * - 0.13\n - >= 4.0, < 5.0\n - >= 3.2\n - 3.7, 3.8, 3.9, 3.10\n * - 0.14\n - >= 5.0, < 6.0\n - >= 3.2\n - 3.8, 3.9, 3.10, 3.11\n * - 0.15\n - >= 5.2\n - >= 4.2\n - 3.8, 3.9, 3.10, 3.11, 3.12\n\nUpgrade considerations (v0.10.8)\n================================\n\n- Template tag ``change_lang`` now needs a second parameter, ``page``\n\nUpgrade considerations (v0.8)\n=============================\n\nThis version includes breaking changes as some key parts of the app have been re-written:\n\n- The most important change is that ``Page`` is now patched with translation fields.\n- ``WAGTAILMODELTRANSLATION_ORIGINAL_SLUG_LANGUAGE`` setting has been deprecated.\n\nTo upgrade to this version you need to:\n\n- Replace the ``WagtailTranslationOptions`` with ``TranslationOptions`` in all translation.py files\n- Run :code:`python manage.py sync_page_translation_fields` at least once to create ``Page``'s translation fields\n- Replace any usages of Wagtail's ``{% slugurl ... %}`` for :code:`wagtail-modeltranslation`'s own ``{% slugurl_trans ... %}``\n- 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.\n\nUpgrade considerations (v0.6)\n=============================\n\nThis version has some important changes as there was a refactoring to include django-modeltranslation as a dependency instead of\nduplicating their code in our version. This allow us to focus on Wagtail admin integration features as django-modeltranslation is\nvery well mantained and is very quickly to fix problems with the latest Django versions. This way we also keep all the django-modeltranslation\nfeatures (if you want you can also customize django-admin, for example). We also provide a new class to create the translation options classes: **WagtailTranslationOptions**\nMost of the changes are related to imports as they change from wagtail-modeltranslation to modeltranslation.\n\nTo upgrade to this version you need to:\n\n- Replace the ``TranslationOptions`` with ``WagtailTranslationOptions`` in all translation.py files\n- The import of the register decorator is now ``from modeltranslation.decorators import register``\n- The import of translator is now ``from modeltranslation.translator import translator``\n\n\nProject Home\n------------\nhttps://github.com/infoportugal/wagtail-modeltranslation\n\nDocumentation\n-------------\nhttp://wagtail-modeltranslation.readthedocs.io/\n",
"bugtrack_url": null,
"license": "New BSD",
"summary": "Translates Wagtail CMS models using a registration approach.",
"version": "0.15.0",
"project_urls": {
"Homepage": "https://github.com/infoportugal/wagtail-modeltranslation",
"Repository": "https://github.com/infoportugal/wagtail-modeltranslation"
},
"split_keywords": [
"django",
" wagtail",
" translation",
" i18n"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "950e1cf0d1233981699acde49b473ddc5d75e0fec75a01940b459e42ebc6ccba",
"md5": "ba08c3baad5e1d5f6158c782d8b4910a",
"sha256": "da49fed109fa1602bd796de844d0e043bf8079d22a894079cdf3d2d54b154eba"
},
"downloads": -1,
"filename": "wagtail_modeltranslation-0.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba08c3baad5e1d5f6158c782d8b4910a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 55810,
"upload_time": "2024-04-03T14:41:14",
"upload_time_iso_8601": "2024-04-03T14:41:14.414686Z",
"url": "https://files.pythonhosted.org/packages/95/0e/1cf0d1233981699acde49b473ddc5d75e0fec75a01940b459e42ebc6ccba/wagtail_modeltranslation-0.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8557e6638f908c4a5bc2f022b216c03294693b5773cc6a7d665ba8e08473d2bb",
"md5": "05b83a91572920e51a4efd6caf55c694",
"sha256": "a0e64896b9b67c3cf362d8b27f293852347fe799090dbe41e32f3200d6fa6ff3"
},
"downloads": -1,
"filename": "wagtail_modeltranslation-0.15.0.tar.gz",
"has_sig": false,
"md5_digest": "05b83a91572920e51a4efd6caf55c694",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 51813,
"upload_time": "2024-04-03T14:41:16",
"upload_time_iso_8601": "2024-04-03T14:41:16.618621Z",
"url": "https://files.pythonhosted.org/packages/85/57/e6638f908c4a5bc2f022b216c03294693b5773cc6a7d665ba8e08473d2bb/wagtail_modeltranslation-0.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-03 14:41:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "infoportugal",
"github_project": "wagtail-modeltranslation",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "wagtail-modeltranslation"
}
JSON
