Dear po4a team, I'd like to renew the workflow of the rulebook of the international unicycling federation. It's a big document (~100 pages) with competition rules for unicycling. It is constantly changing, because the sport is very young and developed a lot. Sadly there is no space for experimental rules that need to be tested first. Right now it is written in MSWord, passed around by email and the translations are not coordinated very well. This worked out for the last 10 years, but I think today we can do much better. How I think it should work: - Many people should be able to write differnt parts of the document at the same time - People need to know what changed at which time, so we need version control - There should be versions with experimental rulesets for testing competitions - If an experimental rule works out, it can be merged into the master document - The translation should be done collaboratively by the community - people should be able to view the current versions (including translations) online and/or print them - If a change to a master/experimental document is made, the translation system is automatically updated, so that the community can start to translate changes immediately. (No regular admin interaction) Here are my ideas so far: - Rewrite the whole thing in LaTeX (can render to HTML or PDF) - Put it in a git repository and manage experimental versions as branches - With every commit render the pdf and html versions. - Translate it (and also the experimental branches) collaboratively with po4a and Pootle and also render the translated documents automatically I think this could solve the issue. But before we start to work I want to know if this is the right approach. Latex and git are no problem. But for the translation I'm not sure. With a new commit in git, we could trigger a po4a-updatepo for the changed latex files in every branch. But is it possible to automatically reinject them into Pootle? How do the translations flow back from Pootle to the build system. If a new language is set up in Pootle, how does it create new documents? Can we do version control for the languages to be able to jump back to an older version of a document with proper translation? I guess you can answer these questions easily and support us to set this up properly.

On 2012/11/8 Felix Dietze wrote: > Dear po4a team, > > I'd like to renew the workflow of the rulebook of the international > unicycling federation. It's a big document (~100 pages) with competition > rules for unicycling. It is constantly changing, because the sport is very > young and developed a lot. Sadly there is no space for experimental rules > that need to be tested first. > > Right now it is written in MSWord, passed around by email and the > translations are not coordinated very well. This worked out for the last 10 > years, but I think today we can do much better. > > How I think it should work: > - Many people should be able to write differnt parts of the document at the > same time > - People need to know what changed at which time, so we need version control > - There should be versions with experimental rulesets for testing > competitions > - If an experimental rule works out, it can be merged into the master > document > - The translation should be done collaboratively by the community > - people should be able to view the current versions (including > translations) online and/or print them > - If a change to a master/experimental document is made, the translation > system is automatically updated, so that the community can start to > translate changes immediately. (No regular admin interaction) > > Here are my ideas so far: > - Rewrite the whole thing in LaTeX (can render to HTML or PDF) > - Put it in a git repository and manage experimental versions as branches > - With every commit render the pdf and html versions. > - Translate it (and also the experimental branches) collaboratively with > po4a and Pootle and also render the translated documents automatically > > I think this could solve the issue. But before we start to work I want to > know if this is the right approach. Latex and git are no problem. But for > the translation I'm not sure. > > With a new commit in git, we could trigger a po4a-updatepo for the changed > latex files in every branch. But is it possible to automatically reinject > them into Pootle? How do the translations flow back from Pootle to the build > system. If a new language is set up in Pootle, how does it create new > documents? Can we do version control for the languages to be able to jump > back to an older version of a document with proper translation? > > I guess you can answer these questions easily and support us to set this up > properly. [...] Hallo Felix, This is very interesting, po4a has been designed for this task; as translators, we were bored with having to look at diffs in original documentation, and wanted instead a system which can keep track of changes automatically. I do not know if some people on this list know enough Pootle to answer your questions, you should contact the Pootle developers, they are very nice people. You did not write it, but it is clear that your document will be splitted into many files. Granularity is up to you, for instance by section or subsection. Translators will translate each file separately. Having a stable branch and a development branch is not a problem per se, but here you may have several experimental branches at the same time, translators will have to track all branches, maybe they will not feel comfortable with that. Another option is to have only one branch, and use specific macros to include the desired experimental rulesets. This is very easy with DocBook XML, but is doable with LaTeX too. In order to help translators focus on the main rules, you should write experimental rules in separate files with a common prefix (and include them conditionally in your document) so that translators know from the filename if this is an experimental rule or not. Like Jonas, I wonder whether LaTeX is the best choice, maybe you could test a single page with different formats and find the most suitable for your writers and translators. Maybe you will eventually choose a format which is supported by Pootle without the need of po4a, that is not a problem ;-) Apart from these minor points, your approach looks fully right. Feel free to ask here more questions if you want, but Pootle developers should be much more helpful than us with respect to Pootle usage. Denis