Better translation docs

docs/index.rst

@@ -63,8 +63,8 @@ Content
    installation
    contributing
    design
-   tutorial
    internationalization
+   tutorial
 
 Reference
 -----------

docs/internationalization.rst

@@ -4,13 +4,12 @@ Internationalization and localization
 
 .. index:: internationalization
 
-Refer to the `Django i18n documentation`_ to get started.
-
-.. _`Django i18n documentation`: https://docs.djangoproject.com/en/dev/topics/i18n/
+Refer to the `Django i18n documentation`_ to get started with
+internationalization (i18n).
 
 
-Using internationalization in your project
-==========================================
+Enabling i18n in Django
+=======================
 
 Make sure you've activated translation for your project
 (the fastest way is to check in your ``settings.py`` file if ``MIDDLEWARE_CLASSES`` includes
@@ -22,35 +21,62 @@ Then compile the messages so they can be used by Django.
 
   python manage.py compilemessages
 
-
 It should get you started !
 
-Contributing to localization
-============================
 
-Django-admin2 has adopted `Transifex`_ to manage the localization process, `join and
-help us`_ making django-admin2 available for everyone !
+Translating django-admin2
+=========================
 
-.. _Transifex: https://www.transifex.com
-.. _`join and help us`: https://www.transifex.com/projects/p/django-admin2/
+The translation of the language files is handled using Transifex_.
+
+Improving existing translations
+-------------------------------
+
+To check out what languages are currently being worked on, check out the
+`Project page`_. If you want to help with one of the translations, open the
+team page by clicking on the language and request to join the team.
+
+.. image:: _static/join_team.png
+    :alt: Button labeled "Join team"
+
+Now you can start translating. Open the language page, select a language
+resource (e.g. *djadmin2.po*).
+
+.. image:: _static/translate_now.png
+    :alt: Button labeled "Translate now"
+
+Then select a string from the list on the left and enter a translation on the
+right side. Finally, click the *Save* button on the top right and you're done.
+
+It is also possible to suggest better translations for existing ones with the
+*Suggest* button on the bottom.
+
+Requesting a new language
+-------------------------
+
+If a language is not available on Transifex_ yet, you can request it with the
+*Request language* button on the `Project page`_.
+
+.. image:: _static/request_language.png
+    :alt: Button labeled "Request language"
 
 
-Using internationalization in the django-admin2 project development
-===================================================================
+Using i18n in the django-admin2 project development
+===================================================
 
-Internationalization
---------------------
+This section is mainly directed at 
 
-Python code
-###########
+Marking strings for translation
+-------------------------------
+
+**Python code**
 
 Make sure to use ugettext or ugettext_lazy on strings that will be shown to the users,
 with string interpolation ( "%(name_of_variable)s" instead of "%s" ) where needed.
 
 Remember that all languages do not use the same word order, so try to provide flexible strings to translate !
 
-Templates
-#########
+**Templates**
 
 Make sure to load the i18n tags and put ``trans`` tags and ``blocktrans`` blocks where needed.
 
@@ -72,12 +98,22 @@ Update the headers of the newly created file to match existing files and start t
 Updating existing locales
 -------------------------
 
+To update the language files with new strings in your .py files / templates:
+
 .. code-block:: bash
 
   cd djadmin2 # or any other package, for instance example/blog
   django-admin.py makemessages -a
 
-  # update the translations
-  # make sure to fix all fuzzy translations
+Then translate the files directly or upload them to Transifex_.
+
+When the translation is done, you need to recompile the new translations:
+
+.. code-block:: bash
 
   django-admin.py compilemessages
+
+
+.. _`django i18n documentation`: https://docs.djangoproject.com/en/dev/topics/i18n/
+.. _transifex: https://www.transifex.com/projects/p/django-admin2/
+.. _project page: https://www.transifex.com/projects/p/django-admin2/