micropython
micropython copied to clipboard
bbcmicrobit
Work in progress - feedback welcome
Hmm... so it seems they have a bug in the readthedocs, as this doesn't seem to work as expected.
- I created a fork of the microbit micropython repository: https://github.com/deshipu/microbit-micropython-pl
- I translated the front page of the documentation to Polish: https://github.com/deshipu/microbit-micropython-pl/blob/master/docs/index.rst
- I created a project on readthedocs pointing to that repository, specifying the language as Polish: https://readthedocs.org/projects/microbit-micropython-pl
- I linked that project as the translation of the microbit-micropython repository.
The result is that the default URL for the microbit-micropython-pl changed to http://microbit-micropython.readthedocs.io/pl/latest/ but that page returns a 404. Visiting http://microbit-micropython-pl.readthedocs.io works correctly, and you can switch the language to English in the dropdown, but switching the other way around doesn't work.
As it's currently described it sounds like each person that would like to create a translation would have to create/copy/fork a github repository on their username, create a read the docs account or projects, and then submit it for inclusion.
If that's the case I think that would fragment the documentation, it would be a bit weird that people that would want to update or complete the official documentation for https://github.com/bbcmicrobit/micropython/ would have to submit pull request to something like https://github.com/carlosperate/microbit-micropython-es , and that's if they are first able to figure out where to send the PR.
I would suggest to change the process so that the intention to create translation would have to be declared as an issue, and then a maintainer could create a repository inside https://github.com/bbcmicrobit to submit pull requests to. Alternatively we could request for the user to transfer ownership of the repository to the bbcmicrobit GH organisation, but that would also need to be a clear expectation.
If that's the case I think that would fragment the documentation, it would be a bit weird that people that would want to update or complete the official documentation for https://github.com/bbcmicrobit/micropython/ would have to submit pull request to something like https://github.com/carlosperate/microbit-micropython-es , and that's if they are first able to figure out where to send the PR.
That's not an issue. There is an "edit on Github" button in the top right corner, that will automatically take you to github, let you edit the file, fork the correct repository and let you create a pull request.
The result is that the default URL for the microbit-micropython-pl changed to http://microbit-micropython.readthedocs.io/pl/latest/ but that page returns a 404.
This issue fixed itself overnight (probably some caching thing somewhere) and the translation now works as expected.
Is there a way of marking a translation to be in progress and highlight it is not finished yet? Should the issue to add the translation be raised as soon as the translation is started, or wait until there is a translation of all the docs? It would be nice to have a way of inviting collaborators too.
I've started the Finnish translation at https://github.com/peconia/micropython-finnish (readthedocs at http://micropython-finnish.readthedocs.io/fi/latest/ ) following what @deshipu did for Polish, but I'm not sure if I should continue with this or wait :)
Is there a way of marking a translation to be in progress and highlight it is not finished yet? Should the issue to add the translation be raised as soon as the translation is started, or wait until there is a translation of all the docs?
I'm not sure about this. Is it ever "finished"? We are not publishing a book, so there is no "deadline" or a cut-off point after which no corrections can be made. I think it's best to link it as soon as possible, and leave the untranslated part in English -- that may be good for inviting collaboration, too, as people can get annoyed with the English text in the middle of translated work, and go fix it.
It would be nice to have a way of inviting collaborators too. Since it's on github, you have all the tools for that that github offers, plus all the traditional means, like sending a link with e-mail, sharing it on the social portals, etc.
I think it would be good to agree on a naming convention, such as "microbit-micropython-XX", where XX is the language code, so that it's easier to search for those translations.
By the way, I just realized that we also need to translate the graphics -- for instance, the comic strip on the first page. Is that available somewhere in some more editable format, like SVG? Or do we have to re-touch the pixels?
Answering my own question, I just found https://pycomic.github.io/ and I can re-generate the comic in Polish: https://goo.gl/5on66z
Just one small detail: I can't translate the word "by" in the title into Polish (well, OK, I can use the web inspector and edit the page's HTML, but that's not something an average translator can do).