Several documentation improvements.

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

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:
 

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 <settings-modeltranslation_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.

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 = '<PROJECT_MODULE>.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 = '<PROJECT_MODULE>.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``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

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

docs/modeltranslation/usage.rst

@@ -90,6 +90,8 @@ language.
 .. todo:: Add more examples.
 
 
+.. _multilingual_manager:
+
 Multilingual Manager
 --------------------