tutorial

tutorial copied to clipboard

Last Saturday at the Django Under the Hood 2016 conference sprint I've started to look into automating the publishing of this tutorial. When translations are made and successfully reviewed they should be published online without manual intervention (e.g. no manual downloading from Crowdin, no manual corrections of broken generated code, no copying images, no pull requests required, etc.).

Instead translators should focus on translating (on Crowdin) and translations should be automatically deployed as soon as they are approved (a.k.a. continuous translation). Technically, this would translate into an automatic build process triggered by Crowdin and executed (probably) on Travis-CI.

Current Challenges

• Crowdin seems to restructure the Markdown code breaking some of the resulting articles.
• A description of what happens to deploy the tutorial after a PR is accepted is missing from the publishing guide.
• A Crowdin project identifier is under version control, but it doesn't seem to work ("Requested project does not exist or API key is not valid" when I try with crowdin-cli-py download).
• I have no appropriate access to the Crowdin project to verify the current project identifier.
• I have no appropriate access to the GitBook organization to verify the current deployment settings.

Observations, Side Notes

• According to @patjouk Crowdin is used, because it supports Markdown (whereas Transifex doesn't).
• GitBook gives the impression to work similar to ReadTheDocs, but I've not yet managed to find out how exactly.
• ReadTheDocs and reStructuredText allow for an established automatic process for publishing documentation including their translations (e.g. using Transifex). That could be an alternative if we can't get the Markdown/Crowdin issues under control.

Help and Feedback Needed

• I'd be interested in details about why it is important to use Markdown, GitBook and Crowdin.
• I'd need the appropriate details of the Crowdin and GitBook setup, or privileges to look those up myself. (@patjouk, I got in touch with you via Crowdin Sunday; I guess you're busy doing the wrap-up of the conference.)

Any support greatly appreciated!

A newer, partially related issue: #1271

I'd be interested in details about why it is important to use Markdown, GitBook and Crowdin.

I'm not aware of any reason why it would have to be these 3 technologies, other than that's what we're currently using and what the contributors and users got used to. I guess none of these are impossible to change, if there's some clear benefit.

Does Transifex support translating prose? If so, how is the prose to be translated presented to translators?

As translating a whole paragraph might be beyond the ability of a single translator, or beyond the amount of work they might want to volunteer in one go, I like that Crowdin splits paragraphs into sentences that can be translated separately, but also shows them in the context of the whole chapter with all the sentences in the right order.

I guess, splitting text up into so-called "segments" is a basic feature every translation software or platform supports.

Their documentation explains how their Live JS implementation does segmentation. It would surprise me if the traditional platform did the segmentation in any other way.