doc: Rework "internationalization" document

Shuffle some things around, add some additional markup, and fix header
styles.

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/intl.rst

@@ -46,14 +46,14 @@ They can be delivered to translators which will transform them to ``.po`` files
 --- so called **message catalogs** --- containing a mapping from the original
 messages to foreign-language strings.
 
-Gettext compiles them into a binary format known as **binary catalogs** through
+*gettext* compiles them into a binary format known as **binary catalogs**
-:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
+through :program:`msgfmt` for efficiency reasons.  If you make these files
-with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
-up automatically.
+will pick them up automatically.
 
 An example: you have a document ``usage.rst`` in your Sphinx project.  The
-gettext builder will put its messages into ``usage.pot``.  Imagine you have
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
-Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
+Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
 be translated you need to follow these instructions:
 
 * Compile your message catalog to a locale directory, say ``locale``, so it
@@ -63,7 +63,8 @@ be translated you need to follow these instructions:
         msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
 
 * Set :confval:`locale_dirs` to ``["locale/"]``.
-* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
+* Set :confval:`language` to ``es`` (also possible via
+  :option:`-D <sphinx-build -D>`).
 * Run your desired build.
 
 
@@ -71,117 +72,124 @@ Translating with sphinx-intl
 ----------------------------
 
 Quick guide
-^^^^^^^^^^^
+~~~~~~~~~~~
 
-`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
-This section describe an easy way to translate with sphinx-intl.
+section describe an easy way to translate with *sphinx-intl*.
 
-#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl`.
+#. Install `sphinx-intl`_.
 
-#. Add configurations to your `conf.py`::
+   .. code-block:: console
+
+      $ pip install sphinx-intl
+
+#. Add configurations to ``conf.py``.
+
+   ::
 
       locale_dirs = ['locale/']   # path is example but recommended.
       gettext_compact = False     # optional.
 
-   This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
+   This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
-   :confval:`gettext_compact` is set to `False` (the Sphinx document is
+   :confval:`gettext_compact` is set to ``False`` (the Sphinx document is
    already configured as such).
 
-#. Extract document's translatable messages into pot files:
+#. Extract translatable messages into pot files.
 
    .. code-block:: console
 
       $ make gettext
 
-   As a result, many pot files are generated under ``_build/gettext``
+   The generated pot files will be placed in the ``_build/gettext`` directory.
-   directory.
 
-#. Setup/Update your `locale_dir`:
+#. Generate po files.
+
+   We'll use the pot files generated in the above step.
 
    .. code-block:: console
 
       $ sphinx-intl update -p _build/gettext -l de -l ja
 
-   Done. You got these directories that contain po files:
+   Once completed, the generated po files will be placed in the below
+   directories:
 
-   * `./locale/de/LC_MESSAGES/`
+   * ``./locale/de/LC_MESSAGES/``
-   * `./locale/ja/LC_MESSAGES/`
+   * ``./locale/ja/LC_MESSAGES/``
 
-#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
+#. Translate po files.
 
-#. make translated document.
+   AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   directory.  An example of one such file, from Sphinx, ``builders.po``, is
+   given below.
+
+   .. code-block:: po
+
+      # a5600c3d2e3d48fc8c261ea0284db79b
+      #: ../../builders.rst:4
+      msgid "Available builders"
+      msgstr "<FILL HERE BY TARGET LANGUAGE>"
+
+   Another case, msgid is multi-line text and contains reStructuredText syntax:
+
+   .. code-block:: po
+
+      # 302558364e1d41c69b3277277e34b184
+      #: ../../builders.rst:9
+      msgid ""
+      "These are the built-in Sphinx builders. More builders can be added by "
+      ":ref:`extensions <extensions>`."
+      msgstr ""
+      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
+      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
+
+   Please be careful not to break reST notation.  Most po-editors will help you
+   with that.
+
+#. Build translated document.
 
    You need a :confval:`language` parameter in ``conf.py`` or you may also
-   specify the parameter on the command line (for BSD/GNU make):
+   specify the parameter on the command line.
+
+   For for BSD/GNU make, run:
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
-   command line (for Windows cmd.exe):
+   For Windows :command:`cmd.exe`, run:
 
    .. code-block:: console
 
       > set SPHINXOPTS=-D language=de
       > .\make.bat html
 
-   command line (for PowerShell):
+   For PowerShell, run:
 
    .. code-block:: console
 
       > Set-Item env:SPHINXOPTS "-D language=de"
       > .\make.bat html
 
-
 Congratulations! You got the translated documentation in the ``_build/html``
 directory.
 
 .. versionadded:: 1.3
 
-   sphinx-build that is invoked by make command will build po files into mo files.
+   :program:`sphinx-build` that is invoked by make command will build po files
-
+   into mo files.
-   If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
-   before make command.
 
+   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
+   command before :command:`make` command.
 
 Translating
-^^^^^^^^^^^
+~~~~~~~~~~~
-
-Translate po file under ``./locale/de/LC_MESSAGES`` directory.
-The case of builders.po file for sphinx document:
-
-.. code-block:: po
-
-   # a5600c3d2e3d48fc8c261ea0284db79b
-   #: ../../builders.rst:4
-   msgid "Available builders"
-   msgstr "<FILL HERE BY TARGET LANGUAGE>"
-
-Another case, msgid is multi-line text and contains reStructuredText
-syntax:
-
-.. code-block:: po
-
-   # 302558364e1d41c69b3277277e34b184
-   #: ../../builders.rst:9
-   msgid ""
-   "These are the built-in Sphinx builders. More builders can be added by "
-   ":ref:`extensions <extensions>`."
-   msgstr ""
-   "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
-   "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
-
-Please be careful not to break reST notation.  Most po-editors will help you
-with that.
-
 
 Update your po files by new pot files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a document is updated, it is necessary to generate updated pot files
+If a document is updated, it is necessary to generate updated pot files and to
-and to apply differences to translated po files.
+apply differences to translated po files.  In order to apply the updates from a
-In order to apply the updating difference of a pot file to po file,
+pot file to the po file, use the :command:`sphinx-intl update` command.
-use the :command:`sphinx-intl update` command.
 
 .. code-block:: console
 
@@ -198,7 +206,7 @@ easy to fetch and push translations.
 .. TODO: why use transifex?
 
 
-#. Install `transifex-client`_
+#. Install `transifex-client`_.
 
    You need :command:`tx` command to upload resources (pot files).
 
@@ -208,8 +216,7 @@ easy to fetch and push translations.
 
    .. seealso:: `Transifex Client documentation`_
 
-
+#. Create your transifex_ account and create new project for your document.
-#. Create your transifex_ account and create new project for your document
 
    Currently, transifex does not allow for a translation project to have more
    than one version of the document, so you'd better include a version number in
@@ -220,8 +227,7 @@ easy to fetch and push translations.
    :Project ID: ``sphinx-document-test_1_0``
    :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
 
-
+#. Create config files for :command:`tx` command.
-#. Create config files for tx command
 
    This process will create ``.tx/config`` in the current directory, as well as
    a ``~/.transifexrc`` file that includes auth information.
@@ -237,7 +243,7 @@ easy to fetch and push translations.
       ...
       Done.
 
-#. Upload pot files to transifex service
+#. Upload pot files to transifex service.
 
    Register pot files to ``.tx/config`` file:
 
@@ -258,15 +264,14 @@ easy to fetch and push translations.
       ...
       Done.
 
-
+#. Forward the translation on transifex.
-#. Forward the translation on transifex
 
    .. TODO: write this section
 
+#. Pull translated po files and make translated HTML.
 
-#. Pull translated po files and make translated html
+   Get translated catalogs and build mo files. For example, to build mo files
-
+   for German (de):
-   Get translated catalogs and build mo files (ex. for 'de'):
 
    .. code-block:: console
 
@@ -277,32 +282,29 @@ easy to fetch and push translations.
       ...
       Done.
 
-   Invoke make html (for BSD/GNU make):
+   Invoke :command:`make html` (for BSD/GNU make):
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
-
 That's all!
 
-
 .. tip:: Translating locally and on Transifex
 
    If you want to push all language's po files, you can be done by using
-   :command:`tx push -t` command.
+   :command:`tx push -t` command.  Watch out! This operation overwrites
-   Watch out! This operation overwrites translations in transifex.
+   translations in transifex.
 
    In other words, if you have updated each in the service and local po files,
    it would take much time and effort to integrate them.
 
 
-
 Contributing to Sphinx reference translation
 --------------------------------------------
 
-The recommended way for new contributors to translate Sphinx reference
+The recommended way for new contributors to translate Sphinx reference is to
-is to join the translation team on Transifex.
+join the translation team on Transifex.
 
 There is `sphinx translation page`_ for Sphinx (master) documentation.
 
@@ -310,8 +312,7 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
 2. Go to `sphinx translation page`_.
 3. Click ``Request language`` and fill form.
 4. Wait acceptance by transifex sphinx translation maintainers.
-5. (after acceptance) translate on transifex.
+5. (After acceptance) Translate on transifex.
-
 
 .. rubric:: Footnotes
 
@@ -320,7 +321,6 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
        for details on that software suite.
 .. [2] Because nobody expects the Spanish Inquisition!
 
-
 .. _`transifex-client`: https://pypi.org/project/transifex-client/
 .. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
 .. _Transifex: https://www.transifex.com/