From 45c7c9e2c5e08460b4db58002f9ee236008334da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1rio?= Date: Thu, 4 Jan 2018 15:09:57 +0000 Subject: [PATCH 1/3] Update management commands.rst [ci skip] --- docs/management commands.rst | 111 +++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) diff --git a/docs/management commands.rst b/docs/management commands.rst index e69de29..b3a75fb 100644 --- a/docs/management commands.rst +++ b/docs/management commands.rst @@ -0,0 +1,111 @@ +.. _management_commands: + +Management Commands +=================== + +.. _management_commands-wagtail_modeltranslation: + +wagtail_modeltranslation +------------------------ + +wagtail_modeltranslation module adds the following management commands. + +.. _management_commands-update_translation_fields: + +The ``update_translation_fields`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command is a proxy to ``django-modeltranslation``'s own ``update_translation_fields``, for more details read the +corresponding documentation on `django-modeltranslation docs +`_. + +In case modeltranslation was installed in an existing project and you +have specified to translate fields of models which are already synced to the +database, you have to update your database schema. + +Unfortunately the newly added translation fields on the model will be empty +then, and your templates will show the translated value of the fields which +will be empty in this case. To correctly initialize the default translation +field you can use the ``update_translation_fields`` command: + +.. code-block:: console + + $ python manage.py update_translation_fields + +.. _management_commands-sync_page_translation_fields: + +The ``sync_page_translation_fields`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 0.8 + +This command compares the database and translated Page model definition (finding new translation +fields) and provides SQL statements to alter ``wagtailcore_page`` table. You should run this command +after installation and after adding a new language to your ``settings.LANGUAGES``. + +.. code-block:: console + + $ python manage.py sync_page_translation_fields + +.. _management_commands-makemigrations_translation: + +The ``makemigrations_translation`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 0.8 + +``wagtail-modeltranslation`` patches Wagtail's ``Page`` model and as consequence Django's original +``makemigrations`` commmand will create migrations for ``Page`` which may create conflicts with +other migrations. To circumvent this issue ``makemigrations_translation`` hides any ``Page`` model changes +and creates all other migrations as usual. Use this command as an alterntive to Django's own +``makemigrations`` or consider using :ref:`management_commands-makemigrations`. + +.. code-block:: console + + $ python manage.py makemigrations_translation + +.. _management_commands-set_translation_url_paths: + +The ``set_translation_url_paths`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Updates url_path translation fields for all pages. + +.. code-block:: console + + $ python manage.py set_translation_url_paths + + +.. _management_commands-wagtail_modeltranslation.makemigrations: + +wagtail_modeltranslation.makemigrations +--------------------------------------- + +To use ``wagtail_modeltranslation.makemigrations`` module commands add ``'wagtail_modeltranslation.makemigrations,'`` +to ``INSTALLED_APPS``. This module adds the following management commands. + +.. _management_commands-makemigrations: + +The ``makemigrations`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command is a proxy for :ref:`management_commands-makemigrations_translation`. It has the added benefit of +overriding Django's own ``makemigrations`` allowing you to run ``makemigrations`` safely without creating +spurious ``Page`` migrations. + +.. code-block:: console + + $ python manage.py makemigrations + +.. _management_commands-makemigrations_original: + +The ``makemigrations_original`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since Django's ``makemigrations`` is overriden by ``wagtail-modeltranslation``'s version use +``makemigrations_original`` to run the Django's original ``makemigrations`` command. Please note +this will likely create invalid ``Page`` migrations, do this only if you know what you're doing. + +.. code-block:: console + + $ python manage.py makemigrations_original From 0bca45dcbbcfbbb3298dff0354ced7b07fcf105a Mon Sep 17 00:00:00 2001 From: Dario Marcelino Date: Thu, 4 Jan 2018 15:12:32 +0000 Subject: [PATCH 2/3] Docs: add management commands to index [ci skip] --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index d40b95d..ad228a6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,6 +50,7 @@ Contents Registering Models advanced settings template tags + management commands recommended reading releases/index AUTHORS From abeadb68714bbca1dd4b8413d60e410354fb261b Mon Sep 17 00:00:00 2001 From: Dario Marcelino Date: Fri, 5 Jan 2018 11:47:46 +0000 Subject: [PATCH 3/3] Docs: add caveats [ci skip] --- docs/caveats.rst | 33 +++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/template tags.rst | 8 +++++--- 3 files changed, 39 insertions(+), 3 deletions(-) create mode 100644 docs/caveats.rst diff --git a/docs/caveats.rst b/docs/caveats.rst new file mode 100644 index 0000000..468a189 --- /dev/null +++ b/docs/caveats.rst @@ -0,0 +1,33 @@ +.. _caveats: + +Caveats +======= + +Wagtail's ``Page`` patch +------------------------ + +``wagtail-modeltranslation`` patches Wagtail's ``Page`` model with translation fields +``title_xx``, ``slug_xx``, ``seo_title_xx``, ``search_description_xx`` and ``url_path_xx`` +where "xx" represents the language code for each translated language. This is done without +migrations through :ref:`management_commands-sync_page_translation_fields`. Since +``Page`` model belongs to Wagtail it's within the realm of possibility that one day Wagtail +may add a conflicting field to ``Page`` thus interfering with ``wagtail-modeltranslation``. + +See also :ref:`management_commands-makemigrations_translation` to better understand how +migrations are managed with ``wagtail-modeltranslation``. + +Wagtail's slugurl +----------------- + +Wagtail's ``slugurl`` tag does not work across languages. To work around this +``wagtail-modeltranslation`` provides a drop-in replacement tag named +:ref:`template tags-slugurl_trans` which by default takes the slug parameter in the +default language. + +Replace any usages of Wagtail's ``{% slugurl 'default_lang_slug' %}`` for + +.. code-block:: django + + {% load wagtail_modeltranslation %} + ... + {% slugurl_trans 'default_lang_slug' %} diff --git a/docs/index.rst b/docs/index.rst index ad228a6..ca8f9d1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,6 +51,7 @@ Contents advanced settings template tags management commands + caveats recommended reading releases/index AUTHORS diff --git a/docs/template tags.rst b/docs/template tags.rst index a9ee8b3..74e85f4 100644 --- a/docs/template tags.rst +++ b/docs/template tags.rst @@ -14,10 +14,12 @@ Use this template tag to get the url of the current page in another language. Th {% load wagtail_modeltranslation %} {% change_lang 'pt' %} -slugurl_trans -=========== +.. _template tags-slugurl_trans: -Use this template tag as a replacement for `slugurl`. +slugurl_trans +============= + +Use this template tag as a replacement for ``slugurl``. .. code-block:: django