[Scummvm-devel] DOC translation problems

[Thierry Crozat]

Le 29 janv. 2012 à 13:24, Simon Sawatzki a écrit :

> 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.

Personally I think the english README and NEWS files should always be provided.

> 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 guess the wiki page would be http://wiki.scummvm.org/index.php/HOWTO-Translate_ScummVM_GUI
It can certainly be expanded a bit (there are only two lines for translations of the README/QuickStart files on that page).
Or maybe it would be best to split instructions for the GUI and README/QuickStart/NEWS files on two different pages.

>   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.

My idea there was to provide:
1) The english README file
2) The english NEWS file
3) The translated README if available and otherwise the translated QuickStart
4) The translated NEWS file if available.

Regarding the points 3 and 4 the Mac disk image contains the files for all the available translations but I am fine with the Windows installer only taking those for the language selected by the user (in addition to the english files). The only case I see were it would be useful to have the files for all the languages installed is for users that don't speak english but for example use french as a primary language and can read German. We have no README file in French, only the QuickStart, so the user might want to also have the German README.

Also the QuickStart is a subpart of the README (i.e. everything that is in the QuickStart is also in the README) so if a README is available I don't really see any advantages to also provide the QuickStart (except maybe that users never read README files but might read a QuickStart if they get stuck?)

Thierry