Updating and internationalizing documentation

You'll solve it soon, I'm sure. In the meantime I will do the language splitting of the manual in my fork...

Put the chapter files in subdirectories (en fr de and es for starters). Then adjust makefiles to use global configuration files and include language subdirectory files. Pretty much what was done at the link in the first post of this thread.

FDR wrote: - How will we manage changes in the long term?

First of all, I think changes in the manual are a lot slower than firmware code, most changes we currently see are associated with new protocol or minor fixes so there is not too much happening in the manual.

FDR wrote: - How will a translator know, which parts of the original has changed, so he can complete the translation with those changes?

For example, we could enable Git Issues with labels for each language. Whoever documents a new feature should open issues for the other languages that updates are needed with english as the "reference manual"

FDR wrote: - What shell we do with those translations, which do not follow the english version close enough?

I think we should "retranslate" based on the english version, if someone is open to do it. I can help with german, Morlacus offered french so we only need russian and spanish translators .

FDR wrote: - What will we do if whole chapters will be missing from some translations?

For the first transition to multi language documentation on github I'd suggest keeping the english texts, as this will make it a lot easier to do a fast translation of a chapter or part of a chapter. This will also easily show parts which have not been translated and are in need of work

FDR wrote: - Will a translator be able to use different pictures, like a screen on the particular language?

We could make subdirectories in the images folder, so if someone wants to make a translated picture he can upload it and change the reference.

FDR wrote: - Do we plan to assist that in the make, or should they simply use different file names as picture links?
...and so on.

See above.


But I'm open for discussion on this, I think the manual can be easily edited even by non-programmers, and since we have it on github, why not make use of the community? With over 10000 downloads on pdf manuals, I'm sure there will be some willing to aid with good documentation if the hurdle isn't too high.

@FDR: I hope you are making progress with CI. I tried something concerning translation - please check your PM

Find this topic looking in recent topics
I have not understood a lot ...and not used in programming except basic, html or some php and work on windows and not used at all in linux.
But I am interested in translating documentation in french.
So I hope There will be a way to do it

My test setup is working locally so far, I really like the tool I tried out. Remaining issues for me:

- why do we build the pdf from pdfindex.rst? It seems useless and gives a lot of trouble with localized pdf builds. If we just build pdf from index.rst it works like a charm...
- should translations be kept in the repository? If yes, Travis will have to push a commit to the repo basically everytime it compiles an updated manual. On the other hand we could run travis only when a (merge) commit to the repo has been made (there is no need for nightly builds as in the firmware in my opinion) so the number of commits will be limited (basically two commits per source manual change, one for english and one from travis pulling in new translations). The other option would be to only keep localizations remote.
- unfortunately every language has to be build separately and makes its output to the same files, so we have to invoke a make, rename the output pdf file (or html directory) and then start the next build. Then we can do all uploads at the end.

I followed you trials
I thought about handling translated files, and while searching the web and looking at other projects it seems like uploading translations back into github seems to be the best option. But this would require a github token for Travis which someone with Travis and github permissions has to do. How would you like the files to be named? DeviationXManual_en.pdf etc?

You misunderstood me. I do not want to push the pdfs to github, their question concerning their name was for uploading them to deviationtx.com.

This is the planned process in travis:will pull new translations from transfixwill then build german pdf, which has to be renamed and uploaded.
After doing make and upload for the remaining languages we can runto generate english sources and upload them to transifex, in case new text has been inserted into the manual on github.
Finally we would runTo make sure the updated translations which have been pulled from Transifex in the first step are also available in the Github repository for local builds or in case something bad happens to Transifex and we need a backup.

edit: if translations were directly edited in GitHub those changes would get discarded in this process. The problem is that ugly things could happen if things get changed in translations on GitHub and Transfix at the same time. I'd suggest seeing Transifex as the translation master, but all translations being pushed to github for backup and local compilation, so there is no need for installing Transfix locally when building the manual.

Well, Transifex is rooted in and devoted to open source and used by many well known projects. There are other solutions to parsing the gettext files, but theirs is definitely the most elegant. If we ever decide to leave Transifex, we still have all translated po files which can also be used with other open source tools.

If we decide to go with Transifex, I would suggest transferring ownership to you and maybe making PB (if he's interested) and me a project administrator if you like.

All right, I'll set things up and make a pull request. To get the build working again you will have to add transifex and github tokens to Travis to make it running again. Can the upload script handle different pdf files in the same category?

Making some good progress. Due to some limitations in rst2pdf (which no longer supports sphinx, so there is no chance for fixes), I had to change building of the pdf to pdflatex which now runs smooth. This changes the looks of the pdf documentation - but in a good way I think. See attached pdf. Another benefit is, that the pdf is now half the size of the original one...