[Po4a-devel] IUF Rulebook translation

[D. Barbier]

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