[Microbit-Python] Microbit Python Doc translation

Sun Feb 12 14:39:09 EST 2017

// +Dani, the translation lead for the micropython documentation

Hi all,

As an update: we have started the Hungarian translation of the
documentation.

   - ReadTheDocs: https://microbit-micropython-hu.readthedocs.io/hu/latest/
   - Github: https://github.com/techtabor/microbit-micropython-hu

*Are you up for connecting our translation with your original
documentation, so that it show up in the RTD languages section?*

According to the RTD instructions
<http://docs.readthedocs.io/en/latest/localization.html#localization-of-documentation>,
you have to mark in your "parent project" our project as a Hungarian
translation.

Best,
Miklos

On Sun, Dec 4, 2016 at 12:58 PM Miklós András Danka <danka.miklos at gmail.com>
wrote:

I think as a first step then, I'll just go ahead and fork the original
repository for a translation.

If some more advanced process is agreed upon, or the documentation is moved
to a new platform, we can always move this first fork as well.

Thanks!
Miklos

On Mon, Nov 28, 2016 at 10:59 PM Miklós András Danka <danka.miklos at gmail.com>
wrote:

Makes a lot more sense! Let me ruminate and explore a bit more.

-Miklos

On Mon, Nov 28, 2016 at 10:51 PM Carlos Pereira Atencio <
carlosperate at gmail.com> wrote:

Readthedocs already offers linked translations, so we can continue using
this platform. As far was what I would be looking for is better support for
translation tracking and updating, so that people could easily do small
contribution without a complex set up or trying to figure out what to
update by manually reading the English and translated documents to spot
unsynchronised bits. I mention some of my concerns with git here:
https://github.com/bbcmicrobit/micropython/pull/371#discussion_r89747053

I feel that ultimately, how live the documentation is in any language will
depend on how active the community is. That's irrespective of the
translation process. No?

I wouldn't quite agree with that, we (as the open source community) always
point to documentation, or in this case translations, as an easy first
step. If we make this difficult we might inadvertently be turning away
valuable contributions. I would expect some of this translations to come
also from not-so-technical communities, teachers for instance are great
candidates, and every time I even mention git/github to teachers I never
hear anything even remotely positive (this specific point is just my
personal experience and should be taken completely anecdotally). If we
ignoring the use of git for this solutions, then it would be a very manual
process to keep track of changes. Yes, "edit this on github" and PRs are
easy, and I think it does work great for normal documentation, but
translations are do not really follow the same model and I don't feel like
git really is the best way to manage them.

On 28 November 2016 at 11:19, Miklós András Danka <danka.miklos at gmail.com>
wrote:

That's true - all I expected from translations support is that they allow
listing translations together and possibly synchronising pages (so if I'm
on page X and click the other language, I'm taken to the right page).

What else are you looking for? More fine-grained support? Support for
tracking/translating each English commit?

I feel that ultimately, how live the documentation is in any language will
depend on how active the community is. That's irrespective of the
translation process. No?

-Miklos

On Mon, Nov 28, 2016 at 10:15 PM Carlos Pereira Atencio <
carlosperate at gmail.com> wrote:

I am not really able to have a proper look until later, but from a very
quick skim gitbook doesn't seem to offer any translation feature to give it
an advantage over readthedocs. They both allow you to add translation to
their document generation, but there isn't any features to be able to
manage and synchronise such translations, no?

Regards,
Carlos

On 28 November 2016 at 11:02, Miklós András Danka <danka.miklos at gmail.com>
wrote:

An alternative is Gitbook: https://www.gitbook.com/

   - As far as I can see, it's free for public non-commercial uses
   - It supports translations: http://toolchain.gitbook.com/languages.html
   - It is non-technical to edit it - git backed, but no need to deal with
   git
   - For a live example, check out the documentation of Redux:
   http://redux.js.org/docs/basics/UsageWithReact.html

Do you expect a reasonably quick decision on this? If these discussions
take a longer time, then I think the best solution is if we fork the repo
and start the translation - leaving time to decide the exact process. If
you expect quick agreement, then we can wait until Gitbook or something
else is set up.

Thoughts?

-Miklos

PS. Nick, thanks for the response! I now requested membership.

On Sun, Nov 27, 2016 at 11:26 PM Carlos Pereira Atencio <
carlosperate at gmail.com> wrote:

Let's not forget we still need to formalise the way we create and process
the translations: https://github.com/bbcmicrobit/micropython/pull/371
There's been some conversation there but not decisions done at all.

On Sun, 27 Nov 2016, 12:13 Nicholas H.Tollervey, <ntoll at ntoll.org> wrote:

Hi Miklós,

Hmmm... I can't find your original email to this mailing list. Also, to
post you need to be a member (you can join here:
https://mail.python.org/mailman/listinfo/microbit) although I get
notified of all the non-member postings so let this one through! Also,
since you're not a member I'm not sure you'll see any replies to the
mailing list (hence me cc'ing you to my reply).

Regarding translation and ReadTheDocs: it would be wonderful to have
Hungarian translations of the documentation! RtD have started to put
advertising on our documentation and there is also work on the pyedu.io
website for Python in education related resources.

I wonder if we shouldn't just put our tutorials on there instead (along
with lots of other education related resources)..?

Thoughts..?

N.

On 27/11/16 06:03, Miklós András Danka wrote:
> Hi,
>
> I haven't got any responses, so I wanted to ping again before I start
> hosting a fork.
>
> Read The Docs supports localisation in this way:
> http://read-the-docs.readthedocs.io/en/latest/localization.html
>
> Would you up for doing this?
>
> Thanks,
> Miklos
>
>
> On Mon, Oct 31, 2016 at 9:26 PM Miklós András Danka
> <danka.miklos at gmail.com <mailto:danka.miklos at gmail.com>> wrote:
>
>     Hello,
>
>     I'm Miklos Danka, a software engineer and a teacher (here's an
>     example
>     <http://blog.miklosdanka.com/tech-camp-beta-the-first-session>). I'm
>     writing regarding the BBC Microbit Python edition - please let me
>     know if this is not the right place or contact for it.
>
>     First of all: *it's really awesome.* Incredible job, especially
>     around the documentation, which even less experienced kids
>     understood well. Very very cool.
>
>     Since I teach kids in Hungary, I wanted to translate the
>     documentation
>     <https://microbit-micropython.readthedocs.io/en/latest/> to
>     Hungarian. My question is: *do you have a recommended/preferred way
>     of publishing the translation?* I can always just fork the
>     repository - but that would miss out on the benefits of having the
>     documentations tracked together at the same website.
>     Would you recommend it as a Sphinx "version" (next to "latest" and
>     "stable")? Or does Sphinx provide and orthogonal translation feature?
>
>     Any ideas/suggestions would be very welcome and appreciated.
>
>     Thanks!
>     Miklos
>
>
>
> _______________________________________________
> Microbit mailing list
> Microbit at python.org
> https://mail.python.org/mailman/listinfo/microbit
>

_______________________________________________
Microbit mailing list
Microbit at python.org
https://mail.python.org/mailman/listinfo/microbit
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/microbit/attachments/20170212/5ca04bbd/attachment-0001.html>