No support for multilingual documentation tools

[Marco Ciampa]

In KiCad EDA there is no support for multilingual documentation tools.
Documentation is written directly with OpenOffice, a simple Wordprocessor, that does not handle automatic multilingual / multiformat document handling like many OpenSource projects already do nowadays. See the GIMP for example.

The problem.
Master documentation is written in OO. Suppose that some volunteer (like me) is avid to translate it into a foreign language. Suppose that starting from a specific version copy, working night and day, in a fiew months he (me) is able to complete it. It wold be already obsolete because of the improvement and new functions applied meanwhile in the master developmente branch. Documentation, if you want to be ready when the development version become stable, must be translated along with the development process.
Suppose you want to update. You (me) have to read all the master copy along with the translated copy do see where the document is changed and how. This work is many times more the translation effort in itself. If the situation do not change this could be a very discouraging factor for translators.

The solution.
The aforementioned GIMP translation team use xml2po to face up to this problem, another (better) tool is Publican (https://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/index.html) but I think that there are many more different tools out there.

A transition to the XML format will have the (benign) side effect to enable context sensitive help, as is in GIMP, much appreciated by the users.

[jean-pierre charras (jp-charras)]

Le 08/08/2014 16:50, Marco Ciampa a écrit :
> Public bug reported:
>
> In KiCad EDA there is no support for multilingual documentation tools.
> Documentation is written directly with OpenOffice, a simple Wordprocessor, that does not handle automatic multilingual / multiformat document handling like many OpenSource projects already do nowadays. See the GIMP for example.
>
> The problem.
> Master documentation is written in OO. Suppose that some volunteer (like me) is avid to translate it into a foreign language. Suppose that starting from a specific version copy, working night and day, in a fiew months he (me) is able to complete it. It wold be already obsolete because of the improvement and new functions applied meanwhile in the master developmente branch. Documentation, if you want to be ready when the development version become stable, must be translated along with the development process.
> Suppose you want to update. You (me) have to read all the master copy along with the translated copy do see where the document is changed and how. This work is many times more the translation effort in itself. If the situation do not change this could be a very discouraging factor for translators.
>
> The solution.
> The aforementioned GIMP translation team use xml2po to face up to this problem, another (better) tool is Publican (https://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/index.html) but I think that there are many more different tools out there.
>
> A transition to the XML format will have the (benign) side effect to
> enable context sensitive help, as is in GIMP, much appreciated by the
> users.
>
> ** Affects: kicad
> Importance: Undecided
> Status: New
>

Support for multilingual documentation is not an easy task.
You have to translate text, but also many screen shots and diagrams.

For new and short doc, we are now using the markdown language (plain
text with few tags).

Master documentation is an other thing.
But what do you mean by: "a *simple* Word processor"?
OpenOffice/LibreOffice (we are using LibreOffice) stores the text using
a XML format (just unzip a .odt file).

There are some specific tools to handle translations, depending on the
word processor you are using.

*You could have a look at omegat (http://www.omegat.org)*

Due to the fact OpenOffice/LibreOffice archives a document (xml files +
images) in a zipped archive, our main concerns is the fact this is a
binary file, which is poorly handled by all version control systems.

Note also: LibreOffice can store the file in a flat xml form (.fodt files)

--
Jean-Pierre CHARRAS

[Marco Ciampa (ciampix)]

Dear Jean-Pierre,
I know that multilingual documentation is not an easy task. The GIMP documentation (see http://docs.gimp.org and
http://docs.gimp.org/2.8/it/ ;-) is full of screenshots: it is a photoretouch program. The xml2po tool also manages the obsolescence of images.

What I am saying here is that if there are tools in place to lessen this burden in the way I have described previously, some people (I am sure) will be more willing to contribute (me, for a start ...).

Tools like omegat IMHO are _not_ suitable for this kind of tasks, i.e. team translations. Even the wonderful markdown language by itself (i.e. without the help of other tools) is not (fully) the answer to this problem. What do we need here is a tool to handle multilingual support to continue changing of template docs so the main authors are free to change whatever they will in the master docs without even caring for translators . This happening while the system handles transparently strings/chapters obsolescence/fuzzy/new and so the translators are free to work individually.

I repeat: there are some tools working in this way. All we need to do is:

1) recognize & understand the problem
2) decide which tools fits best
3) adopt the tool chosen

Feel free to contact me to clarify this issue, via email or irc or whatever.
Please forgive my bad english.

[Nick Østergaard (nickoe)]

Just for reference: https://github.com/ciampix/kicad-doc

[Seth Hillbrand (sethh)]

Is this still the case for any of the docs or have we fully switched?

[Wayne Stambaugh (stambaughw)]

AFAIK, all of our user documentation is asciidoc and is translated.

[Nick Østergaard (nickoe)]

This was essentially already addressed with kicad 4.0, I guess it is most appropiate to mark this bugs as released. So that is what I will do.