Docs: Improved introduction to i18n for Cog authors and Translators (…

…+fixed broken docs test!)

docs/framework_i18n.rst

@@ -17,26 +17,28 @@ that use the framework. The framework is based on the popular gettext format,
 (with some modifications), which is the standard for providing translations in 
 lots of different software projects.
 
-* `.pot` files are typically generated by the original author of the cog, and 
+* ``.pot`` files are typically generated by the original author of the cog, and 
   contain the basic messages in en_US (the language Red is written in), and is 
   used as a template for translators to build their translations on.
-* `.po` files (portable objects) are language specific, for example `en-GB.po` 
-  for British English, or `en-ES.po` for Spanish. Note that Red uses a `-` 
-  character in the filename, not a `_` which is often seen as as the standard.
-* `locales/` directory, where `.po` files are stored.
+* ``.po`` files (portable objects) are language specific, for example 
+  ``en-GB.po`` for British English, or ``en-ES.po`` for Spanish. Note that Red 
+  uses a ``-`` character in the filename, not a ``_`` which is often seen as as 
+  the standard.
+* ``locales/`` directory, where ``.po`` files are stored.
 
 So, if your are the author of a Cog, or you are adding translations for the first
-time to python code, you would probably generate `.pot` file to make your code 
+time to python code, you would probably generate ``.pot`` file to make your code 
 easily translatable. See below for instructions.
 
-If you are trying to translate part of Red, or a Cog, you would write a `.po` file.
+If you are trying to translate part of Red, or a Cog, you would write a ``.po`` 
+file.
 
 A technical detail, is that Red actually uses a slightly modified version of 
-`pygettext`, called `redgettext` (https://github.com/Cog-Creators/redgettext). 
+``pygettext``, called ``redgettext`` (https://github.com/Cog-Creators/redgettext). 
 This is mostly just an implementation detail though and does not affect Cog 
 authors or translators. If you are used to gettext, it is important to explain 
-that Red does *not use `.mo` files* - it is not necessary to run `msgfmt` or 
-other tools, it reads the `.po` files directly.
+that Red does *not use `.mo` files* - it is not necessary to run ``msgfmt`` or 
+other tools, it reads the ``.po`` files directly.
 
 ~~~~~~~~~~~~~~~
 For Cog authors
@@ -51,8 +53,8 @@ steps are;
 * Translate literal strings (eg "This is a test command") to use the underscore 
   function like _("This a test command")
 * Use redgettext to generate a message.pot file
-* Write a test `.po` file, and put it in your `locales/` directory relative
-  to your `.py` code.
+* Write a test ``.po`` file, and put it in your ``locales/`` directory relative
+  to your ``.py`` code.
 
 .. code-block:: python
 
@@ -72,10 +74,12 @@ steps are;
 
 
 
-After making your cog, generate a :code:`messages.pot` file
+After making your Cog, and using the _() function to make your strings 
+translatable, you will need to generate a :code:`messages.pot` file. 
 
 We recommend using redgettext - a modified version of pygettext for Red.
-You can install redgettext by running :code:`pip install redgettext` in a command prompt.
+You can install redgettext by running :code:`pip install redgettext` in a 
+command prompt.
 
 To generate the :code:`messages.pot` file, you will now need to run
 :code:`python -m redgettext -c [path_to_cog]`
@@ -88,18 +92,19 @@ For Translators
 ~~~~~~~~~~~~~~~
 
 If your Cog is already made to be translatable by the original Cog author, you
-simply need to write a `.po` file for your language.
+simply need to write a ``.po`` file for your language.
 
-You can use a simple text editor to write a `.po` file, but you also use popular
+You can use a simple text editor to write a ``.po`` file, but you also use popular
 tools like `poedit
 <https://poedit.net/>`_ to translate the strings in the messages.pot file. There 
 are also free online websites that can be used to get you started, like 
-https://www.potranslate.com/upload .
+https://crowdin.com/ which some developers link to their code repositories, or 
+https://www.potranslate.com/upload where you can just upload the ``.pot`` file.
 
-Once you have written your .po file, you will need to send it back to the Cog 
+Once you have written your ``.po`` file, you will need to send it back to the Cog 
 author. Most Cog authors would prefer pull requests on GitHub, but it's probably
 best to open an issue with the original Cog author to discuss how they would 
-like to receive your `.po` file language contribution.
+like to receive your ``.po`` file language contribution.
 
 -------------
 API Reference