diff --git a/docs/framework_i18n.rst b/docs/framework_i18n.rst
index b305a8e12e3..5adc6859c6a 100644
--- a/docs/framework_i18n.rst
+++ b/docs/framework_i18n.rst
@@ -7,9 +7,54 @@
 Internationalization Framework
 ==============================
 
------------
-Basic Usage
------------
+--------
+Tutorial
+--------
+
+The Red framework supports translations into different languages, making it easy 
+for translators to contribute new language files to the Red project, and to Cogs
+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 
+  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.
+
+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`` files 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.
+
+A technical detail, is that Red actually uses a slightly modified version of 
+``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.
+
+~~~~~~~~~~~~~~~
+For Cog authors
+~~~~~~~~~~~~~~~
+
+For authors of Cogs, it's very easy to make your bot translatable using the
+Translator class provided - code samples can be found below. In summary, the 
+steps are:
+
+* Import the i18n Translator class and cog_i18n decorator.
+* Decorate your class with @cog_i18n
+* 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.
 
 .. code-block:: python
 
@@ -27,14 +72,14 @@ Basic Usage
             """command description"""
             await ctx.send(_("This is a test command"))
 
---------
-Tutorial
---------
 
-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]`
@@ -42,8 +87,24 @@ This file will contain all strings to be translated, including
 docstrings.
 (For advanced usage check :code:`python -m redgettext -h`)
 
-You can now use a tool like `poedit
-<https://poedit.net/>`_ to translate the strings in your messages.pot file.
+~~~~~~~~~~~~~~~
+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.
+
+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://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 
+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.
 
 -------------
 API Reference