From 0e028f27138712304f8fa8019d293a59a5ab3a1d Mon Sep 17 00:00:00 2001 From: Dirk Eschler Date: Sat, 17 Nov 2012 01:36:41 +0100 Subject: [PATCH] Several documentation improvements. --- README.rst | 5 ++- docs/modeltranslation/admin.rst | 8 ++-- docs/modeltranslation/commands.rst | 17 ++++---- docs/modeltranslation/installation.rst | 55 +++++++++++++++++--------- docs/modeltranslation/registration.rst | 44 +++++++++++---------- docs/modeltranslation/usage.rst | 2 + 6 files changed, 79 insertions(+), 52 deletions(-) diff --git a/README.rst b/README.rst index 79ead56..e2f5734 100644 --- a/README.rst +++ b/README.rst @@ -21,10 +21,11 @@ model class. Features ======== -- Unlimited number of target languages - Add translations without changing existing models -- Django admin support +- Fast, because translation fields are stored in the same table - Supports inherited models +- Django admin support +- Unlimited number of target languages Project Home diff --git a/docs/modeltranslation/admin.rst b/docs/modeltranslation/admin.rst index 08e99b4..db7cf2e 100644 --- a/docs/modeltranslation/admin.rst +++ b/docs/modeltranslation/admin.rst @@ -33,9 +33,9 @@ inline related classes in modeltranslation derive from, implements a special method which is ``def formfield_for_dbfield(self, db_field, **kwargs)``. This method does the following: -1. Copies the widget of the original field to each of it's translation fields. -2. Checks if the original field was required and if so makes - the default translation field required instead. +1. Copies the widget of the original field to each of its translation fields. +2. Checks if the original field was required and if so makes the default + translation field required instead. get_form/get_fieldsets/_declared_fieldsets @@ -156,7 +156,7 @@ A translated inline must derive from one of the following classes: Just like ``TranslationAdmin`` these classes implement a special method ``formfield_for_dbfield`` which does all the patching. -For our example we assume that there is new model called ``Image``. Its +For our example we assume that there is a new model called ``Image``. The definition is left out for simplicity. Our ``News`` model inlines the new model: diff --git a/docs/modeltranslation/commands.rst b/docs/modeltranslation/commands.rst index 198bb81..8ba582d 100644 --- a/docs/modeltranslation/commands.rst +++ b/docs/modeltranslation/commands.rst @@ -14,7 +14,7 @@ database, you have to update your database schema manually. Unfortunately the newly added translation fields on the model will be empty then, and your templates will show the translated value of the fields (see -Rule 1 below) which will be empty in this case. To correctly initialize the +Rule 1) which will be empty in this case. To correctly initialize the default translation field you can use the ``update_translation_fields`` command: @@ -22,13 +22,16 @@ command: $ ./manage.py update_translation_fields -Taken the News example from above this command will copy the value from the -news object's ``title`` field to the default translation field ``title_de``. -It only does so if the default translation field is empty otherwise nothing -is copied. +Taken the news example used throughout the documentation this command will copy +the value from the news object's ``title`` field to the default translation +field ``title_de``. It only does so if the default translation field is empty +otherwise nothing is copied. -.. note:: The command will examine your ``settings.LANGUAGES`` variable and the - first language declared there will be used as the default language. +.. note:: + Unless you configured modeltranslation to + :ref:`override the default language ` + the command will examine your ``settings.LANGUAGES`` variable and the first + language declared there will be used as the default language. All translated models (as specified in the project's ``translation.py`` will be populated with initial data. diff --git a/docs/modeltranslation/installation.rst b/docs/modeltranslation/installation.rst index 8a95d23..d2e262d 100644 --- a/docs/modeltranslation/installation.rst +++ b/docs/modeltranslation/installation.rst @@ -115,7 +115,9 @@ and ``en`` in your project, set the ``LANGUAGES`` variable like this (where Advanced Settings ***************** -Modeltranslation also has some advanced settings to customize its behaviour: +Modeltranslation also has some advanced settings to customize its behaviour. + +.. _settings-modeltranslation_default_language: ``MODELTRANSLATION_DEFAULT_LANGUAGE`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -147,8 +149,8 @@ Modeltranslation uses an autoregister feature similiar to the one in Django's admin. The autoregistration process will look for a ``translation.py`` file in the root directory of each application that is in ``INSTALLED_APPS``. -A setting ``MODELTRANSLATION_TRANSLATION_FILES`` is provided to limit or extend -the modules that are taken into account. +A setting ``MODELTRANSLATION_TRANSLATION_FILES`` is provided to extend the +modules that are taken into account. Syntax: @@ -168,12 +170,13 @@ Example: 'projects.translation', ) -.. note:: Modeltranslation up to version 0.3 used a single project wide - registration file which was defined through - ``MODELTRANSLATION_TRANSLATION_REGISTRY = '.translation'``. - For backwards compatibiliy the module defined through this setting is - automatically added to ``MODELTRANSLATION_TRANSLATION_FILES``. A - ``DeprecationWarning`` is issued in this case. +.. note:: + Modeltranslation up to version 0.3 used a single project wide registration + file which was defined through + ``MODELTRANSLATION_TRANSLATION_REGISTRY = '.translation'``. + For backwards compatibiliy the module defined through this setting is + automatically added to ``MODELTRANSLATION_TRANSLATION_FILES``. A + ``DeprecationWarning`` is issued in this case. ``MODELTRANSLATION_CUSTOM_FIELDS`` @@ -183,14 +186,10 @@ Default: ``()`` (empty tuple) .. versionadded:: 0.3 -``Modeltranslation`` officially supports ``CharField`` and ``TextField``. - -.. versionadded:: 0.4 - -Support for ``FileField`` and ``ImageField``. - -In most cases subclasses of the supported fields will work fine, too. Other -fields aren't supported and will throw an ``ImproperlyConfigured`` exception. +Modeltranslation supports the fields listed in the +:ref:`supported_field_matrix`. In most cases subclasses of the supported +fields will work fine, too. Unsupported fields will throw an +``ImproperlyConfigured`` exception. The list of supported fields can be extended by defining a tuple of field names in your ``settings.py``. @@ -203,11 +202,31 @@ Example: .. warning:: This just prevents modeltranslation from throwing an - ``ImproperlyConfigured`` exception. Any non text-like field will most + ``ImproperlyConfigured`` exception. Any unsupported field will most likely fail in one way or another. The feature is considered experimental and might be replaced by a more sophisticated mechanism in future versions. +``MODELTRANSLATION_AUTO_POPULATE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Default: ``False`` + +.. versionadded:: 0.5 + +This setting controls if the :ref:`multilingual_manager` should automatically +populate language field values in its ``create`` method, so that these two +statements can be considered equivalent: + +.. code-block:: python + + News.objects.create(title='-- no translation yet --', _populate=True) + +.. code-block:: python + + News.objects.create(title='-- no translation yet --') + + ``MODELTRANSLATION_DEBUG`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/modeltranslation/registration.rst b/docs/modeltranslation/registration.rst index a662691..3f3ce5a 100644 --- a/docs/modeltranslation/registration.rst +++ b/docs/modeltranslation/registration.rst @@ -3,10 +3,9 @@ Registering Models for Translation ================================== -The ``modeltranslation`` app can translate ``CharField`` and ``TextField`` -based fields (as well as ``FileField`` and ``ImageField`` as of version 0.4) -of any model class. For each model to translate a translation option class -containing the fields to translate is registered with the modeltranslation app. +Modeltranslation can translate model fields of any model class. For each model +to translate a translation option class containing the fields to translate is +registered with a special object called the ``translator``. Registering models and their fields for translation requires the following steps: @@ -14,17 +13,17 @@ steps: 1. Create a ``translation.py`` in your app directory. 2. Create a translation option class for every model to translate. 3. Register the model and the translation option class at the - ``modeltranslation.translator.translator`` + ``modeltranslation.translator.translator``. The modeltranslation application reads the ``translation.py`` file in your app directory thereby triggering the registration of the translation options found in the file. A translation option is a class that declares which fields of a model to -translate. The class must derive from ``modeltranslation.ModelTranslation`` -and it must provide a ``fields`` attribute storing the list of fieldnames. The -option class must be registered with the -``modeltranslation.translator.translator`` instance. +translate. The class must derive from +``modeltranslation.translator.TranslationOptions`` and it must provide a +``fields`` attribute storing the list of fieldnames. The option class must be +registered with the ``modeltranslation.translator.translator`` instance. To illustrate this let's have a look at a simple example using a ``News`` model. The news in this example only contains a ``title`` and a ``text`` field. @@ -102,7 +101,7 @@ expected. Changes Automatically Applied to the Model Class ------------------------------------------------ -After registering the ``News`` model for translation an SQL dump of the news +After registering the ``News`` model for translation a SQL dump of the news app will look like this: .. code-block:: console @@ -123,9 +122,9 @@ app will look like this: COMMIT; Note the ``title_de``, ``title_en``, ``text_de`` and ``text_en`` fields which -are not declared in the original News model class but rather have been added by -the modeltranslation app. These are called *translation fields*. There will be -one for every language in your project's ``settings.py``. +are not declared in the original ``News`` model class but rather have been +added by the modeltranslation app. These are called *translation fields*. There +will be one for every language in your project's ``settings.py``. The name of these additional fields is build using the original name of the translated field and appending one of the language identifiers found in the @@ -142,19 +141,22 @@ the translated models. In case you are translating an existing project and your models have already been synced to the database you will need to alter the tables in your database and add these additional translation fields. Note that all added fields are -declared ``null=True`` not matter if the original field is required. In other -words - all translations are optional. To populate the default translation -fields added by the modeltranslation application you can use the -``update_translation_fields`` command below. See -:ref:`commands-update_translation_fields` section for more infos on this. +declared ``blank=True`` and ``null=True`` no matter if the original field is +required or not. In other words - all translations are optional. To populate +the default translation fields added by the modeltranslation application you +can use the ``update_translation_fields`` command below. See +:ref:`commands-update_translation_fields` for more infos on this. +.. _supported_field_matrix: + Supported Fields Matrix ----------------------- -While the main purpose of modeltranslation is to translate text-like fields, translating other -fields can be useful in several situations. The table lists all model fields available in Django and -gives an overview about their current support status: +While the main purpose of modeltranslation is to translate text-like fields, +translating other fields can be useful in several situations. The table lists +all model fields available in Django and gives an overview about their current +support status: =============================== === === Model Field 0.4 0.5 diff --git a/docs/modeltranslation/usage.rst b/docs/modeltranslation/usage.rst index 1c3987c..079c331 100644 --- a/docs/modeltranslation/usage.rst +++ b/docs/modeltranslation/usage.rst @@ -90,6 +90,8 @@ language. .. todo:: Add more examples. +.. _multilingual_manager: + Multilingual Manager --------------------