[Scummvm-devel] DOC translation problems

Travis Howell kirben at optusnet.com.au
Mon Jan 30 14:30:00 CET 2012


On 30/01/2012 12:24 AM, Simon Sawatzki wrote:
> 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.

Even an out dated README is still useful, if it is in a users native 
language. I don't see the point in always including only the English 
version either, when users might not understand any English at all.

All translations should be installed, or only the native language should 
be installed. With Start Menu only offering links to documentation in 
native language, in the case of Windows installer.

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

No, I think adding notes about SHA1 ID, or any other developer specific 
notes to documentation is a very bad idea. We have had several releases 
with developer notes included in documentation in the past, since the 
developer notes were often not removed before release.

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

The QuickStart file offers a brief quick guide for people, who usually
wouldn't even look through our large README file.




More information about the Scummvm-devel mailing list