Add guide to how to translate documentation

doc/_static/custom.css

@@ -68,3 +68,7 @@ div.sphinxsidebar h3 a {
     background-color: rgba(255, 255, 255, 0.2) !important;
     border-bottom: none !important;
 }
+
+ol li {
+    margin: 1em 0;
+}

doc/contributing.rst

@@ -101,3 +101,66 @@ How to run tests
 The tests can be run with
 
     python3 setup.py test
+
+
+.. _translating:
+
+Helping to translate the documentation
+--------------------------------------
+
+Pygame Zero's APIs will always be English, but we can bring Pygame Zero to more
+users around the world if the documentation is available in their language.
+
+If you are fluent in another language, please consider contributing by
+translating all or part of the documentation.
+
+The documentation is written in reStructuredText_, which is a text-based markup
+language for technical documentation. As much as possible, the existing
+formatting should be preserved. reStructuredText isn't too difficult once you
+get used to it.
+
+Creating a translation is done by creating a separate repository on Github with
+a copy of the documentation, rewritten (at least in part) into the language you
+would like to support. One advantage of this is that you can work on
+translations at your own pace, without having to submit pull requests back to
+the ``pgzero`` project itself. Please see the `translation guide`_ on Read The
+Docs for details.
+
+If this sounds like something you could tackle, here's how you might go about
+it:
+
+1. First, open an issue on the `pgzero issue tracker`_. You should search for
+   an existing issue covering the translation you want to do, before opening a
+   new one. This will help ensure that you don't do translation work that has
+   already been done by someone else (perhaps you can collaborate instead).
+2. Create a new Github repository under your user, called pgzero-*language*,
+   eg. ``pgzero-spanish`` if you're going to translate into Spanish.
+3. Clone the repository to your own computer.
+4. Download the Pygame Zero ``doc/`` directory and commit it in your project.
+   You can do this by extracting them from `repository ZIP file`_. You only
+   need the ``doc/`` directory from the ZIP file. You can delete the other
+   files.
+5. Now, work through the .rst files in the docs directory, translating, using
+   your preferred editor. You should commit regularly, and push your commits to
+   Github.
+6. Post a link to your repository as a comment in the Github issue you created
+   in step 1. You can do this as soon as you have some progress to show; this
+   will help people collaborate with you on the translation if they are
+   interested.
+7. `Set up the documentation to build on Read The Docs`__. Again, post a
+   comment on the Github issue when you have this working.
+8. We can then link up the new, translated documentation with the Pygame Zero
+   documentation.
+
+.. _reStructuredText: http://www.sphinx-doc.org/en/master/rest.html
+.. _`translation guide`: https://docs.readthedocs.io/en/latest
+                         /localization.html#project-with-multiple-translations
+.. _`pgzero issue tracker`: https://github.com/lordmauve/pgzero/issues/new
+.. _`repository ZIP file`: https://github.com/lordmauve/pgzero/archive/master.zip
+
+.. __: https://docs.readthedocs.io/en/latest/getting_started.html#import-your-docs
+
+Note that Pygame Zero will have updates, and the documentation will be changed
+accordingly. Using Git it is possible to see a diff of what changed in the
+English documentation, so that you can make corresponding changes in the
+translated documentation.

doc/roadmap.rst

@@ -8,6 +8,20 @@ This document just lays out some goals for future releases, but there is **no
 guarantee** that these targets will be hit.
 
 
+Translations
+------------
+
+Pygame Zero is aimed at young users, whose English skills might not be good
+enough to read the documentation if it isn't in their own language.
+
+Adding translations of the documentation would help to bring Pygame Zero to new
+users. This is something that needs contributors to help with. My own language
+skills aren't good enough!
+
+Please see :ref:`the translating guide <translating>` if you think you can
+help.
+
+
 Gamepad Support
 ---------------
 
@@ -23,7 +37,7 @@ nearly all more modern gamepads have at least as many buttons and axes.
 
 This feature needs to be added in a way that will not **require** a gamepad to
 play any Pygame Zero game, in order to follow the principle of
-:ref:`accessibility`_.
+:ref:`accessibility`.
 
 .. _`Pi Hut`: https://thepihut.com/products/raspberry-pi-compatible-usb-gamepad-controller-snes-style
 .. _Amazon: https://www.amazon.co.uk/s/ref=nb_sb_noss_2?url=search-alias%3Delectronics&field-keywords=usb+snes