diff --git a/docs/devguide/translation.rst b/docs/devguide/translation.rst new file mode 100644 index 000000000..77cc367c2 --- /dev/null +++ b/docs/devguide/translation.rst @@ -0,0 +1,43 @@ +.. _dev-translate: + +============ +Translations +============ + +The Python community is a diverse and cosmopolitan place. Our documentation +should be available for users in many different languages and for many different +locales. + +This document explains how to go about translating this documentation. + +Read The Docs +------------- + +Currently we host our documentation on http://readthedocs.org. We use Sphinx to +make the documentation happen. + +The relevant documentation for localisation in ReadTheDocs is here: + +https://docs.readthedocs.io/en/latest/localization.html#project-with-multiple-translations + +Put simply, each new translation is a separate project, presumably a Sphinx +based repository on GitHub, that contains the translated resources and is linked +to ReadTheDocs in the usual way - making sure its locale is set appropriately. + +It's possible for this "core" project to link to these other projects as +"translations of" this one. + +Read the Docs automatically figures out the relationships and displays the +appropriate links between all the related translation projects. + +I want to Translate! +-------------------- + +Great stuff! Thank you (in advance) for your support! + +* Make a new Sphinx project that mirrors the structure of the ``docs`` directory in this project. Call the project something obvious like: ``microbit-micropython-es`` (for the Spanish translation). +* Register the project on ReadTheDocs (see: https://docs.readthedocs.io/en/latest/getting_started.html) +* Create a new issue pointing to the new ReadTheDocs project that forms the new translation. We do this so others have visibility of what's being done. Submit the issue here: https://github.com/bbcmicrobit/micropython/issues/new +* After a quick check and review that things look in order we'll link you as a translation! + +That's it! :-) diff --git a/docs/index.rst b/docs/index.rst index 622d742db..c06cf0c26 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -85,6 +85,7 @@ Projects related to MicroPython on the BBC micro:bit include: devguide/installation devguide/flashfirmware devguide/repl + devguide/translation devguide/devfaq devguide/contributing