diff --git a/README.rst b/README.rst index c0cc5ae..2c146e8 100755 --- a/README.rst +++ b/README.rst @@ -52,7 +52,7 @@ Quick start pip install wagtail-modeltranslation -2. Add "wagtail_modeltranslation" to your INSTALLED_APPS setting like this (before all apps that you want to translate):: +2. Add 'wagtail_modeltranslation' to your ``INSTALLED_APPS`` setting like this (before all apps that you want to translate):: INSTALLED_APPS = ( ... @@ -60,39 +60,40 @@ Quick start 'wagtail_modeltranslation.makemigrations', ) -3. Add "django.middleware.locale.LocaleMiddleware" to MIDDLEWARE_CLASSES on your settings.py:: +3. Add 'django.middleware.locale.LocaleMiddleware' to ``MIDDLEWARE`` on your ``settings.py``:: - MIDDLEWARE_CLASSES = ( + MIDDLEWARE = ( ... - 'django.middleware.locale.LocaleMiddleware', + 'django.middleware.locale.LocaleMiddleware', # should be after SessionMiddleware and before CommonMiddleware ) -4. Enable i18n on settings.py:: +4. Enable i18n on ``settings.py``:: USE_I18N = True -5. Define available languages on settings.py:: +5. Define available languages on ``settings.py``:: + + from django.utils.translation import gettext_lazy as _ LANGUAGES = ( - ('pt', u'Português'), - ('es', u'Espanhol'), - ('fr', u'Francês'), + ('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:: +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) +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) @@ -109,7 +110,7 @@ This version includes breaking changes as some key parts of the app have been re To upgrade to this version you need to: -- Replace the ``WagtailTranslationOptions`` with ``TranslationOption`` in all translation.py files +- 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. @@ -125,7 +126,7 @@ Most of the changes are related to imports as they change from wagtail-modeltran To upgrade to this version you need to: -- Replace the ``TranslationOption`` with ``WagtailTranslationOptions`` in all translation.py files +- 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`` diff --git a/docs/Installation.rst b/docs/Installation.rst index 88415a6..178aa24 100644 --- a/docs/Installation.rst +++ b/docs/Installation.rst @@ -34,76 +34,78 @@ Installing using the source Quick Setup -===== +=========== To setup the application please follow these steps: -1. In the settings/base.py file: +1. In your settings file: - - Add wagtail_modeltranslation to the INSTALLED_APPS + - Add 'wagtail_modeltranslation' to ``INSTALLED_APPS`` - .. code-block:: console + .. code-block:: console - INSTALLED_APPS = ( - ... - 'wagtail_modeltranslation', - ) + INSTALLED_APPS = ( + ... + 'wagtail_modeltranslation', + 'wagtail_modeltranslation.makemigrations', + ) + - Add 'django.middleware.locale.LocaleMiddleware' to ``MIDDLEWARE`` (``MIDDLEWARE_CLASSES`` before django 1.10). - - Add django.middleware.locale.LocaleMiddleware to MIDDLEWARE_CLASSES. - - - .. code-block:: console - - MIDDLEWARE_CLASSES = ( - ... - - 'django.middleware.locale.LocaleMiddleware', - ) + .. code-block:: console + MIDDLEWARE = ( + ... + 'django.middleware.locale.LocaleMiddleware', # should be after SessionMiddleware and before CommonMiddleware + ) - Set ``USE_I18N = True`` .. _language_settings: - - Configure your LANGUAGES. + - Configure your ``LANGUAGES`` setting. - The LANGUAGES variable must contain all languages you will use for translation. The first language is treated as the - *default language*. + The ``LANGUAGES`` variable must contain all languages you will use for translation. The first language is treated as the *default language*. - Modeltranslation uses the list of languages to add localized fields to the models registered for translation. - For example, to use the languages Portuguese, Spanish and French in your project, set the LANGUAGES variable like this - (where ``pt`` is the default language). In required fields the one for the default language is marked as required (for more advanced usage check `django-modeltranslation required_languages `_.) + Modeltranslation uses the list of languages to add localized fields to the models registered for translation. + For example, to use the languages Portuguese, Spanish and French in your project, set the ``LANGUAGES`` variable like this + (where ``pt`` is the default language). In required fields the one for the default language is marked as required (for more advanced usage check `django-modeltranslation required_languages `_.) - .. code-block:: console + .. code-block:: console + from django.utils.translation import gettext_lazy as _ - LANGUAGES = ( - ('pt', u'Portugese'), - ('es', u'Spanish'), - ('fr', u'French'), - ) + LANGUAGES = ( + ('pt', _('Portuguese')), + ('es', _('Spanish')), + ('fr', _('French')), + ) -.. warning:: + .. warning:: - When the LANGUAGES setting isn't present in ``settings/base.py`` (and neither is ``MODELTRANSLATION_LANGUAGES``), it defaults to Django's global LANGUAGES setting instead, and there are quite a few languages in the default! + When the ``LANGUAGES`` setting isn't present in ``settings.py`` (and neither is ``MODELTRANSLATION_LANGUAGES``), it defaults to Django's global LANGUAGES setting instead, and there are quite a few languages in the default! + .. note:: + + To learn more about preparing Wagtail for Internationalisation check the `Wagtail i18n docs `_. 2. Create a ``translation.py`` file in your app directory and register ``TranslationOptions`` for every model you want to translate. -.. code-block:: console + .. code-block:: console - from .models import foo - from modeltranslation.translator import TranslationOptions - from wagtail_modeltranslation.translation import register + from .models import foo + from modeltranslation.translator import TranslationOptions + from modeltranslation.decorators import register - @register(foo) - class FooTR(TranslationOptions): - fields = ( - 'body', - ) + @register(foo) + class FooTR(TranslationOptions): + fields = ( + 'body', + ) +3. Run ``python manage.py makemigrations`` followed by ``python manage.py migrate``. This will add the tranlation fields to the database, repeat every time you add a new language or register a new model. -3. Run ``python manage.py makemigrations`` followed by ``python manage.py migrate``. This will add extra fields in the database. +4. Run ``python manage.py sync_page_translation_fields``. This will add translation fields to Wagtail's ``Page`` table, repeat every time you add a new language. +5. If you're adding ``wagtail-modeltranslation`` to an existing site run ``python manage.py update_translation_fields``. -4. Define the panels for the original fields, as you normally would, as wagtail-modeltranslation will generate the panels for the translated fields. +6. Define the panels for the original fields, as you normally would, as wagtail-modeltranslation will generate the panels for the translated fields.