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