Document the translation proccess and translation maintenance process

[das-g]

trafficstars

Issue description

As far as I know, non-English versions of the tutorial are initially created on Crowdin by translating the English "original". However there seem to be several ways to change existing non-English versions:

• suggest changes on Crowdin (which probably makes sense for language-specific stuff, like phrasing, grammar, ...)
• pull requests on GitHub (which probably makes sense for changing a common thing (e.g. code) in several languages at once, so that they stay in sync)

What way is preferred for what kind of contributions and how do they interact? (When and how are changes from Crowdin integrated into the GitHub repo? When are new versions deployed to GitBook and tutorial.djangogirls.org?)

Language

Is this related to a specific language of the tutorial?

All except English

Operating system

What operating system does this issue relate to?

(not applicable)

[ekohl]

For me the relation with Crowdin is unclear. I'm happy to merge typo changes that someone else has approved.

If we want to allow PRs on translations I'd suggest we start using labels for each language. In another project we run a bot to automatically assign labels based on the directory changes were made in. I could probably run that for Django Girls if there's interest/agreement on this.

The https://help.github.com/articles/about-codeowners/ can also be used to assign teams to each language though perhaps this can get in the way when you want to make a pure code change (like shell commands) in all languages. Then you'd need to get approval from every language maintainer.

[das-g]

If we want to allow PRs on translations I'd suggest we start using labels for each language.

As only contributors with push/write permission can assign labels to issues, an automation like you describe would be needed for this to add any advantage.

The https://help.github.com/articles/about-codeowners/ can also be used to assign teams to each language

That seems like a good idea, especially to get the respective "language team" attention and maybe get PRs reviewed in a more timely manner. From the documentation:

Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.

:+1:

Using this feature with teams is a good idea, so that we won't have to hard-code individual people.

though perhaps this can get in the way when you want to make a pure code change (like shell commands) in all languages. Then you'd need to get approval from every language maintainer.

It looks like requiring approval is optional:

When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.

(emphasis mine)

[magul]

I would share what I know regarding translation and Github <-> Crowdin relation:

From community perspective we have at least two documents, that try to describe, how to contribute translations here:

• README in this repository
• Django Girl's translation guide AFAIK none of them prohibit to contribute to translation using Github PR.

There's also at least two channels on Django Girls slack: #translations and #tutorial, where ad hoc discussion may occur (I rarely there, but I've just logged in and see e.g. discussion regardin Korean translation between @sujinleeme and @RachellCalhoun ).

For what I know, @RachellCalhoun is the primary person, that's responsible for translators community/translations policy. We spoke (also with @aniav ) around year ago about how to maintain translations. After initial hipotesis to abandon Crowdin at all, @RachellCalhoun returned with feedback, that major part of community want to use Crowdin, so it's still running.

From technical perspective we use two-way integration Github <-> Crowdin:

• every time something land on master branch here, it's automatically pushed to Crowdin, there's a mask to only include /en subdirectory in translations sources, so whatever new lands in /en subdirectory here cause Crowdin to include it in translation source (and cause drop in translation coverage). That part works pretty fine.
• major shortcoming is a way, how Crowdin push translations to Github - the only way to configure it is to push all new contributions on one branch (here it's named crowdin_master and Crowdin automatically opens a pull request for it and there's no way to disable this branch/pull request creation - for pull request see: #1193). From our perspective this branch is (nearly) usless, as we don't want to push to our master all target languages, that were set on Crowdin (there are a lot of languages with translation coverage less then 50%), so I just create extremaly simple script, that I run whenever I got an email from Crowdin, that any translation was completed, see: https://github.com/magul/dg-bot (another problem here is that You need to be project manager to obtain API key, that is required to rebuild project assets on Crowdin, so it cannot be run by anybody). This script produces branches for every language (at least in theory) and apply newest changes in that languages to appropriate files). It was used by me few times in past, see: #1270, #1249, #1246, #1232, #1210 and #1201).

From my personal perspective (fixing the way Crowdin push code to Gihub) Crowdin provide a lot of value:

• it allows to work on translation in team rather then separately
• it track progress with whatever that land in master branch here and drop coverage for every target language there if new things occurs.

Regarding deployment - it's really simpe, we have Travis-CI build that only check if any pull request is buildable (there were situation that pull request got merged, but Gitbook was not able to build it) and whatever lands in master branch is pushed to Gitbook, so whatever we have on Gihub master branch here should be available on https://tutorial.djangogirls.org.

[magul]

Another (not mentioned in previous comment) thing is what actually beta means (see: LANGS,md) - again, AFAIK that's not described anywhere, for my personal needs I treat any translated language on Crowdin as a beta until it get proofreaded.

[goanpeca]

@magul are the tutorial extensions and coach guide and organizer guides also setup with crowdin in a similar fashion as the main tutorial?

[magul]

AFAIK we don't have such setup. This tutorial belongs on Crowdin to @olasitarska (just because Crowdin doesn't support Github-based organizations, yet again AFAIK).

We (Django Girls) could create there an account via some official email to move tutorial away from Ola's account there (or not). We could also try to migrate rest of resources there but it will require some communication with Crowdin staff, as they do not provide free project by default (You need to provide a proof, that's your project is indeed open source).

[goanpeca]

AFAIK we don't have such setup. This tutorial belongs on Crowdin to @olasitarska (just because Crowdin doesn't support Github-based organizations, yet again AFAIK).

Understood

We (Django Girls) could create there an account via some official email to move tutorial away from Ola's account there (or not).

That could probably be useful, it could be the "bot account, e.g djangogirls-bot" of django girls organization so that that user is not just a crowdin thing, and maybe also move your bot code there ?

We could also try to migrate rest of resources there but it will require some communication with Crowdin staff, as they do not provide free project by default (You need to provide a proof, that's your project is indeed open source).

I understand it might require some extra steps but I think it is definitely worth it!

[das-g]

it could be the "bot account, e.g djangogirls-bot"

Let's move the hyphen: We should ask Diana Nock, whether she'd be OK with us naming the account django-girlbot and using her intrepid comic character as its avatar picture.

[goanpeca]

Let's move the hyphen: We should ask Diana Nock, whether she'd be OK with us naming the account django-girlbot and using her intrepid comic character as its avatar picture.

Love the idea :-) !

Thoughts @magul ?

[goanpeca]

How could we speed this setup a bit, coach, and organizers guides are pretty important assets. Any way I can help?

[magul]

That could probably be useful, it could be the "bot account, e.g djangogirls-bot" of django girls organization so that that user is not just a crowdin thing, and maybe also move your bot code there ?

I would stick with DjangoGirls as an organization on Crowdin (that way tutorial here and there will belong to entities with the same name).

How could we speed this setup a bit, coach, and organizers guides are pretty important assets. Any way I can help?

I would suggest to ask @RachellCalhoun (and maybe @aniav ) before, as she is (they are) in constant contact with our translators community. BTW we should not forget about tutorial-extentions.

Let's move the hyphen: We should ask Diana Nock, whether she'd be OK with us naming the account django-girlbot and using her intrepid comic character as its avatar picture.

We could use such bot account for official Crowdin->Github integration (where Crowdin push to dedicated branch on our Github all changes to all files and maintains open pull request with that branch, see: #1193). Right now it uses @aniav account.

and maybe also move your bot code there ?

I'm fine with moving that simple script to DjangoGirls organization, I don't know if django-girlbot account would be better place for it. The second thing here is that I would advise against deployng this script as full automatic solution - there's just so litle work that actually required infrastructure maintanance will take more time than executing it manually (and it will require developing more sophisticated way how to deal with localisation with the same language, e.g. pt-PT and pt-BR, which because it so little work is done manually).

[bittner]

It's roughly 2.5 years ago since I last looked into automating the translation and publishing process. Could someone take a look at issue #902, please, and clarify the questions asked therein? That would be helpful.