[Scummvm-devel] DOC translation problems

[Simon Sawatzki]

Hi everyone,

for some time now we allow translations of the README and NEWS file. This is a great thing so users can not even use ScummVM in their language but also easily comprehend the helping documents in their language. However, in the way we do it, I see some problems.

In the Windows release, the installer is set up so that only the translation of the selected language is installed. I see the problem there that the translation might not always be up-to-date. Although we can ask translators to update their translation to the newest state at release points, it may not always happen and I see the danger that we feature obsolete versions of files and the users might not know that ScummVM has reached another stage already.
   My suggestion is to always install the English original document also - at least if it isn't assured that the translation is up-to-date. To check this, we could make some system that compares the SHA1 ID of the current README or NEWS file with the one that the translator wrote at the bottom of the translation file (I always do that to know where I have stopped working and to make it easier for a new translator to continue my work should I ever abandon it). If the translation is up-to-date, only the translation should be installed, if it isn't, both the translation and the original document file should be installed. If possible, the translation then should contain a header in the translated language that points out that the translation might not be up-to-date and that the user might prefer to read the English file.

Also, we should give more instructions to translators on how to do their translations. The most important one for me is - as I have stated above - to tell them that it is essentially important for the master branch to always include on which SHA1 ID the translation is based on. For stable releases that note can be removed to not unneccessarily confuse the end user. Is there already a wiki page for this?
   I wanted to point this out since I noticed that we feature some full README translations without those notes and it might be very hard to update them when the translator hasn't worked on it for some time and doesn't remember the version it was based on.

The next and last issue I see is with the QuickStart file. Thierry created it originally to have a template for translators who don't have the time or will to translate the full README. Thus, it is reduced to the most important points. However, now it is included by default in every build. I especially see it as nonsense that it does mention that it is a translation to English users as it is just meant to be a template for translators. We have already got a quickstart section in the big README which is easy to find, so I don't think we really need to include this extra file in the builds.

I am looking forward to hearing your points of view and solutions to the problems that I pointed out. Discussion is encouraged.

Kind regards
Simon Sawatzki
-- 
Empfehlen Sie GMX DSL Ihren Freunden und Bekannten und wir
belohnen Sie mit bis zu 50,- Euro! https://freundschaftswerbung.gmx.de