Add headings to translations docs.

docs/source/translations.rst

@@ -14,26 +14,36 @@ Translations
    ./locale/locales.js those which you don't need. Remember to rebuild the
    minified file afterwards.
 
-The gettext POT file located in ./locale/converse.pot is the template
-containing all translations and from which for each language an individual PO
+----------------------------------------------
+Updating the translations template (.pot file)
+----------------------------------------------
+
+The gettext `.pot` file located in
+`./locale/converse.pot <https://github.com/jcbrand/converse.js/blob/master/locale/converse.pot>`_
+is the template containing all translations and from which for each language an individual PO
 file is generated.
 
-The POT file contains all translateable strings extracted from converse.js.
+The `.pot` file contains all translateable strings extracted from converse.js.
 
-To make a user facing string translateable, wrap it in the double underscore helper
+To make a user-facing string translateable, wrap it in the double underscore helper
 function like so:
 
 .. code-block:: javascript
 
     __('This string will be translated at runtime');
 
-After adding the string, you'll need to regenerate the POT file, like so:
+After adding the string, you'll need to regenerate the POT file:
 
 ::
 
     make pot
 
-To create a new PO file for a language in which converse.js is not yet
+
+-------------------------------------------
+Making translations file for a new language
+-------------------------------------------
+
+To create a new translations file for a language in which converse.js is not yet
 translated into, do the following
 
 .. note:: In this example we use Polish (pl), you need to substitute 'pl' to your own language's code.
@@ -43,7 +53,22 @@ translated into, do the following
     mkdir -p ./locale/pl/LC_MESSAGES
     msginit -i ./locale/converse.pot -o ./locale/pl/LC_MESSAGES/converse.po -l pl
 
-You can then create or update the PO file for a specific language by doing the following:
+Please make sure to add the following attributes at the top of the file (under
+*Content-Transfer-Encoding*). They are required as configuration settings for Jed,
+the Javascript translations library that we're using.
+
+.. code-block:: po
+
+    "domain: converse\n"
+    "lang: pl\n"
+    "plural_forms: nplurals=2; plural=(n != 1);\n"
+
+
+--------------------------------------
+Updating an existing translations file
+--------------------------------------
+
+You can update the `.po` file for a specific language by doing the following:
 
 .. note:: In this example we use German (de), you need to substitute 'de' to your own language's code.
 
@@ -57,23 +82,17 @@ To do this for ALL languages, run:
 
     make po
 
-The resulting PO file is then what gets translated.
-
-If you've created a new PO file, please make sure to add the following
-attributes at the top of the file (under *Content-Transfer-Encoding*). They are
-required as configuration settings for Jed, the Javascript translations library
-that we're using.
+The resulting `.po` file is then what gets translated.
 
-.. code-block:: po
-
-    "domain: converse\n"
-    "lang: de\n"
-    "plural_forms: nplurals=2; plural=(n != 1);\n"
 
+-----------------------------------------------------
+Generating a Javascript file from a translations file
+-----------------------------------------------------
 
-Unfortunately `Jed <http://slexaxton.github.io/Jed>`_ cannot use the PO files directly. We have to generate from it
-a file in JSON format and then put that in a .js file for the specific
-language.
+Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for
+translations in converse.js cannot use the `.po` files directly. We have
+to generate from it a file in JSON format and then put that in a `.js` file
+for the specific language.
 
 To generate JSON from a PO file, you'll need po2json for node.js. Run the
 following command to install it (npm being the node.js package manager):
@@ -86,7 +105,7 @@ You can then convert the translations into JSON format:
 
 ::
 
-    po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json
+    po2json -p -f jed -d converse locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json
 
 Now from converse.json paste the data as a value for the "locale_data" key in the
 object in the language's .js file.