Add docs about empty_values (close #211).

docs/modeltranslation/admin.rst

@@ -319,3 +319,17 @@ A few simple policies are applied:
 
     class NewsAdmin(TranslationAdmin):
         group_fieldsets = True
+
+
+.. _admin-formfield:
+
+Formfields with None-checkbox
+*****************************
+
+There is the special widget which allow to choose whether empty field value should be stores as
+empty string or ``None`` (see :ref:`forms-formfield-both`).
+In ``TranslationAdmin`` some fields can use this widget regardless of their ``empty_values``
+setting::
+
+    class NewsAdmin(TranslationAdmin):
+        both_empty_values_fields = ('title', 'text')

docs/modeltranslation/forms.rst

@@ -0,0 +1,91 @@
+.. _forms:
+
+ModelForms
+==========
+
+Editing multilanguage models with all translation fields in the admin backend is quite sensible.
+However, presenting all model fields to the user on the frontend may be not the right way.
+Here comes the ``TranslationModelForm`` which strip out all translation fields::
+
+    from news.models import News
+    from modeltranslation.forms import TranslationModelForm
+
+    class MyForm(TranslationModelForm):
+        class Meta:
+            model = News
+
+Such a form will contain only original fields (title, text - see :ref:`example <registration>`).
+Of course, upon saving, provided values would be set on proper attributes, depending on the user
+current language.
+
+
+Formfields and nullability
+--------------------------
+
+.. versionadded:: 0.7.1
+
+.. note::
+    Please remember that all translation fields added to model definition are nullable
+    (``null=True``), regardless of the original field nullability.
+
+In most cases formfields for translation fields behave as expected. However, there is one annoying
+problem with ``models.CharField`` - probably the most commonly translated field type.
+
+The problem is that default formfield for ``CharField`` stores empty values as empty strings
+(``''``), even if field is nullable
+(see django `ticket #9590 <http://code.djangoproject.com/ticket/9590>`_).
+
+Thus formfields for translation fields are patched by `MT`. Following rules apply:
+
+.. _formfield_rules:
+
+- If original field is not nullable, empty value would be saved as ``''``;
+- If original field is nullable, empty value would be saved as ``None``.
+
+To deal with complex cases, these rules can be overridden per model or even per field
+(using ``TranslationOptions``)::
+
+    class NewsTranslationOptions(TranslationOptions):
+        fields = ('title', 'text',)
+        empty_values = None
+
+    class ProjectTranslationOptions(TranslationOptions):
+        fields = ('name', 'slug', 'description',)
+        empty_values = {'name': '', 'slug': None}
+
+If a field is not mentioned while using dict syntax, the :ref:`default rules <formfield_rules>`
+apply.
+
+This configuration is especially useful for fields with unique constraints::
+
+    class Category(models.Model):
+        name = models.CharField(max_length=40)
+        slug = models.SlugField(max_length=30, unique=True)
+
+Because the ``slug`` field is not nullable, its translation fields would store empty values as
+``''`` and that would result in error when 2 or more ``Categories`` are saved with
+``slug_en`` empty - unique constraints wouldn't be satisfied. Instead, ``None`` should be stored,
+as several ``None`` values in database don't violate uniqueness::
+
+    class CategoryTranslationOptions(TranslationOptions):
+        fields = ('name', 'slug')
+        empty_values = {'slug': None}
+
+
+.. _forms-formfield-both:
+
+None-checkbox widget
+********************
+
+Maybe there is a situation when somebody want to store in a field both empty strings and ``None``
+values. For such a scenario there is third configuration value: ``'both'``::
+
+    class NewsTranslationOptions(TranslationOptions):
+        fields = ('title', 'text',)
+        empty_values = {'title': None, 'text': 'both'}
+
+It results in special widget with a None-checkbox to null a field. It's not recommended in frontend
+as users may be confused what this `None` is. Probably only useful place for this widget is admin
+backend; see :ref:`admin-formfield`.
+
+To sum up, only valid ``empty_values`` values are: ``None``, ``''`` and ``'both'``.

docs/modeltranslation/index.rst

@@ -14,6 +14,7 @@ Table of Contents
    installation
    registration
    usage
+   forms
    admin
    commands
    caveats

modeltranslation/fields.py

@@ -177,7 +177,7 @@ class TranslationField(object):
         There are 3 different formfields:
         - CharField that stores all empty values as empty strings;
         - NullCharField that stores all empty values as None (Null);
-        - NullableField that can store both None and empty_string.
+        - NullableField that can store both None and empty string.
 
         By default, if no empty_values was specified in model's translation options,
         NullCharField would be used if the original field is nullable, CharField otherwise.