docs for translations

apps/translations/fields.py

@@ -92,7 +92,7 @@ def __set__(self, instance, value):
 
 
 class TranslatedFieldMixin(object):
-    """Mixin that fetches all ``TranslatedField``s after instantiation."""
+    """Mixin that fetches all ``TranslatedFields`` after instantiation."""
 
     def __init__(self, *args, **kw):
         super(TranslatedFieldMixin, self).__init__(*args, **kw)
@@ -119,8 +119,8 @@ def _fetch_translations(self, ids, lang):
         """
         Performs the query for finding Translation objects.
 
-        ``ids`` is a list of the foreign keys to the object's translations
-        ``lang`` is the language of the current request
+        - ``ids`` is a list of the foreign keys to the object's translations
+        - ``lang`` is the language of the current request
 
         Override this to search for translations in an unusual way.
         """

apps/translations/models.py

@@ -27,10 +27,13 @@ def __unicode__(self):
 
     @classmethod
     def new(cls, string, locale, id=None):
-        """Jumps through all the right hoops to create a new translation."""
-        if not string:
-            return
+        """
+        Jumps through all the right hoops to create a new translation.
 
+        If ``id`` is not given a new id will be created using
+        ``translations_seq``.  Otherwise, the id will be used to add strings to
+        an existing translation.
+        """
         if id is None:
             # Get a sequence key for the new translation.
             cursor = connection.cursor()

docs/topics/translations.rst

@@ -0,0 +1,58 @@
+.. _translations:
+
+============================
+Translating Fields on Models
+============================
+
+The ``translations`` app defines a :class:`~translations.models.Translation`
+model, but for the most part, you shouldn't have to use that directly.  When you
+want to create a foreign key to the ``translations`` table, use
+:class:`translations.fields.TranslatedField`.  This subclasses Django's
+:class:`django.db.models.ForeignKey` to make it work with our special handling
+of translation rows.
+
+A minimal Addon model looks like this::
+
+    import amo
+    from translations.fields import TranslatedField
+
+    class Addon(amo.ModelBase):
+        name = TranslatedField()
+        description = TranslatedField()
+
+:class:`amo.ModelBase` inherits from
+:class:`translations.fields.TranslatedFieldMixin`, which fetches all of a
+model's translations during initialization.  It first tries to fetch strings for
+the current locale, and then looks for any missing strings in the default
+locale.  If you want to change this behavior, it should be enough to override
+:meth:`_fetch_translations <translations.fields.TranslatedFieldMixin._fetch_translations>`.
+
+
+Creating New Translations
+-------------------------
+
+If you need to create new
+:class:`Translations <translations.models.Translation>` without the automagic
+helpers behind :class:`~translations.fields.TranslatedField`, use
+:meth:`Translation.new <translations.models.Translation.new>`.
+
+.. automethod:: translations.models.Translation.new
+
+
+``translations.fields``
+-----------------------
+
+.. module:: translations.fields
+
+.. autoclass:: translations.fields.TranslatedField
+
+.. autoclass:: translations.fields.TranslatedFieldMixin
+    :members: _set_translated_fields, _fetch_translations
+
+
+``translations.models``
+-----------------------
+
+.. module:: translations.models
+.. autoclass:: translations.models.Translation
+.. autoclass:: translations.models.TranslationSequence