Updating and internationalizing documentation

More
29 Mar 2017 15:44 #60906 by Moeder
You'll solve it soon, I'm sure. In the meantime I will do the language splitting of the manual in my fork...

Please Log in or Create an account to join the conversation.

More
29 Mar 2017 16:01 #60907 by FDR
How do you plan to do that?

Please Log in or Create an account to join the conversation.

More
29 Mar 2017 16:12 #60908 by Moeder
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.

Please Log in or Create an account to join the conversation.

More
29 Mar 2017 17:10 #60914 by FDR
OK, that is half of the technical part, and I see, that we will be able to build the translated documentations from that.
My concers are these:
- How will we manage changes in the long term?
- How will a translator know, which parts of the original has changed, so he can complete the translation with those changes?
- What shell we do with those translations, which do not follow the english version close enough?
- What will we do if whole chapters will be missing from some translations?
- Will a translator be able to use different pictures, like a screen on the particular language?
- Do we plan to assist that in the make, or should they simply use different file names as picture links?
...and so on.

Please Log in or Create an account to join the conversation.

More
29 Mar 2017 20:51 #60920 by Moeder

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.

Please Log in or Create an account to join the conversation.

More
31 Mar 2017 04:23 #60967 by Moeder
@FDR: I hope you are making progress with CI. I tried something concerning translation - please check your PM

Please Log in or Create an account to join the conversation.

More
31 Mar 2017 08:08 #60969 by Morlacus
Replied by Morlacus on topic Updating and internationalizing documentation
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

Please Log in or Create an account to join the conversation.

More
31 Mar 2017 10:42 #60975 by FDR
Of course your help is welcome!
Moeder is in the process of finding a better way to help the translation.
So far I like it, but I've not yet tried to work on a translation in it.

After that we still need to automate the building process of the translated docs too, and I'm not finished yet with the upload of them.

Please Log in or Create an account to join the conversation.

More
31 Mar 2017 15:32 #60986 by Moeder
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.

Please Log in or Create an account to join the conversation.

More
31 Mar 2017 21:02 #60997 by FDR
The first succesful uploads are in the Downloads/Documentation section.

Don't ask me why it took so long... :S

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 08:10 #61004 by Moeder
I followed you trials :P
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?

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 09:09 #61008 by FDR
Yep, the language postfixes would be fine, but I don't get why do you want to store the translated and compiled PDF back into GitHub?
I see the need of storing the translated sources, but I don't know yet how transifex will save that into GitHub. I guess it would use the standardized language or language+location abbrevations for that.

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 10:05 - 01 Apr 2017 14:03 #61009 by Moeder
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:
tx pull -a -f
will pull new translations from transfix
make -e SPHINXOPTS="-D language='de'" pdf
will then build german pdf, which has to be renamed and uploaded.
After doing make and upload for the remaining languages we can run
make gettext
tx push -s
to generate english sources and upload them to transifex, in case new text has been inserted into the manual on github.
Finally we would run
git add sources/locales
git commit -m 'Adding updated translations from Transifex'
git push
To 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.
Last edit: 01 Apr 2017 14:03 by Moeder. Reason: additional information

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 13:26 #61013 by FDR
Sorry, I see now.
As I wrote, the language postfixes will be fine.

I don't fully understand the document building process, so I would leave the makefile and the .travis.yml to you, but of course if some admin actions are needed I'm more then happy to help. ;)

I like the transifex way.
While we usually only use open source tools, it is free for open source projects, so I have no argument against it.
Would you redirect transifex to the main DeviationTX/deviation-manual repository, or make me an admin to allow me to do so?

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 14:08 #61016 by Moeder
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.

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 14:18 #61018 by FDR
Deal.

Please Log in or Create an account to join the conversation.

More
01 Apr 2017 14:43 #61021 by Moeder
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?

Please Log in or Create an account to join the conversation.

More
02 Apr 2017 00:20 - 02 Apr 2017 01:02 #61041 by Moeder
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...

File Attachment:

File Name: Deviation8...nual.pdf
File Size:1,429 KB


File Attachment:

File Name: Deviation8...4-01.pdf
File Size:1,433 KB
Attachments:
Last edit: 02 Apr 2017 01:02 by Moeder. Reason: edit: added Hungarian manual with translations pulled from transifex

Please Log in or Create an account to join the conversation.

More
02 Apr 2017 18:55 #61086 by FDR
Not bad.
I see some artefacts in the translated one, like the chapter names are wrong in the page footers, but otherwise promising...

Please Log in or Create an account to join the conversation.

More
02 Apr 2017 18:59 #61087 by FDR
@Moeder
Is there a way to migrate the translations into the main repo when you will switch your's to that, or will they vanish?
i.e. should I continue the transation there, or should I wait?

Please Log in or Create an account to join the conversation.

Time to create page: 0.065 seconds
Powered by Kunena Forum