Work in progress - feedback welcome #371
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
There was a problem hiding this comment. This bit didn't seem all that clear to me from the https://docs.readthedocs.io/en/latest/localization.html#project-with-multiple-translations page. How is this link between the doc projects created? Is there a configuration page on readthedocs? a project file that needs to go to one or more repositories? There was a problem hiding this comment. Yes, there is a configuration page at https://readthedocs.org/dashboard/microbit-micropython/translations/ that we will use to add any translation projects. There was a problem hiding this comment. Right, so the administrators would basically add the repository links for each supported language. Is that configuration page also used to indicate which language the repository represents? Or does the repository creator need to do anything to indicate the language? There was a problem hiding this comment. The creator of the repository needs to set the proper language on theirs readthedocs page. We can check if that is set up correctly before linking to it. There was a problem hiding this comment. Okay, got it, thanks for the clarification again :) |
||
|
|
||
| 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). | ||
|
There was a problem hiding this comment. I think it would be better to actually make a fork of the microbit repository -- then we can rebase the new repository on top of the main repository to see what changes in the documentation need to be translated. Alternatively, we could move the docs to a separate repository, and fork that. There was a problem hiding this comment.
I am not quite sure I understand how that rebase would be that useful. If I fork this repository, and start editing all the documentation files, then an initial rebase will basically show me all the English text changed to the new language, fair enough. But then if the English documentation is updated any rebase will start getting a bunch of conflicts and even after resolving them, unless you can speak the translated language, there would be no way to see if the text is up to date (as the rebase would be changing the commit timestamp). There was a problem hiding this comment. Actually, looking how large the microbit micropython repository is (16MB), I really think we should split the docs off to a separate repository. There was a problem hiding this comment. The conflicts are the whole point of the rebase -- they will show you where a new translation is needed. Of course, they will be resolved by people knowing both languages -- the translators themselves. There was a problem hiding this comment. I also don't understand why the rebase would help, but maybe I'm missing something. After the first translation, any diffs (changes) on the original English version would not apply well to the newly translated version. Is this wrong? My feeling is that you'll have to track changes in the English version, and then "human-apply" the English-diff onto the new language. Forking+rebase is useful to preserve/propagate changes in the setup and configuration. There was a problem hiding this comment. Right, we can always switch to something better when we find it. There was a problem hiding this comment. I don't have a solution, but I could imagine a simple script that would pull the changes from the master, merge them, and then find the conflict markers and replace them with some Sphinx syntax to make them render nicely (we could add some CSS to make the old translated text appear with some background, and display the updated English text on hover, or something like that). Of course replacing the conflict markers in a way that doesn't mangle the restructured text syntax is a non-trivial task, but I think I could write something that at least handles most of the cases. Then we can have that script run as a part of There was a problem hiding this comment. Yeah they sound like feasible solutions, but if it's hard enough to get experienced developers to run test scripts before submitting a PR, then I would expect most PR submissions to not have followed these steps locally, much less to manually configure git hooks. So ideally something on the There was a problem hiding this comment. You can checkout the pull request with git, and run 'make html' to generate the html locally. There is restructured text preview in github, but it doesn't understand Sphinx directives, so while it will be fine for normal text, it will fail for the reference docs. There was a problem hiding this comment. Fortunately, for translations the markup will remain largely the same, only the words will change. |
||
| * Register the project on ReadTheDocs (see: https://docs.readthedocs.io/en/latest/getting_started.html) | ||
|
There was a problem hiding this comment. Not sure if we don't want to have all the projects created under the same user, or at least a "common" user to have access rights to all of them. There was a problem hiding this comment. Does readthedocs have anything similar or parallel to github organisations? There was a problem hiding this comment. Just to clarify, were you suggesting to have all the github repositories for each translation under the same user/"hub"/organisation, or were you referring to a readthedocs user? There was a problem hiding this comment. I was thinking about the readthedocs user, but of course it would also make sense to have a github organization for them. |
||
| * 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! :-) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've never publish docs on readthedocs before, so this question comes mostly from my ignorance in this respect: Will this localised repository contain the markdown/restructuredtext files in master, and the Sphinx HTML output on a gh-pages branch with a CNAME file? Or is it enough to have the files in the repository and the build and publish process is then taken care by readthedocs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You just put the restructured text sources in there, just like the microbit repository does (see https://github.com/bbcmicrobit/micropython/tree/master/docs) and readthedocs takes care of everything else, including re-building everything on every commit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh that's great, thanks for the clarification @deshipu.