Re: schema files

[Christian Rose <menthos gnome org>]

fre 2003-07-11 klockan 14.25 skrev Murray.Cumming@Comneon.com:
> The release team has heard that lots of schema (gconf, I suppose) files
> might be difficult to translate or somehow poorly internationalised, or
> might have english text that should be rewritten. Could someone explain the
> problem to us, with examples? Maybe we can then make the issue more widely
> known.

To be clear on the terminology used here: schemas messages = all <short>
and <long> descriptions (and possibly other tags) for gconf keys in
schemas files that are marked for translation. A sample list should be
provided in
http://bugzilla.gnome.org/buglist.cgi?long_desc=schemas&long_desc_type=substring&keywords=GNOMEVER2.3%2Cstring&keywords_type=allwords.

I don't remember off the top of my head any particular instances where
schemas messages were just entirely impossible to translate correctly,
i.e. pure localization problems. Instead almost all of the issues I
myself have encountered are of the second kind, "English text that
should be rewritten" due to being somehow badly written in the first
place, and thus as a consequence causing more or less severe problems in
the translation step.

A large part of the problems can be divided into the following
categories:

1) Consistency problems
2) Typos or in other ways incorrect language
3) Wrong terminology used
4) References to literal values not enclosed in double quotes
5) Outdated or plain wrong messages

1) is very common. It seems different contributors add schemas entries
at different points in time, and often pay very little attention to how
other schemas entries are written when doing that, causing schemas
descriptions to be formulated vastly different in even the same files
sometimes. It helps translators *a lot* if messages are always
formulated the same way and made consistent. See below for some
consistency guidelines. Example reports are #115680 and #114590.

2) is also very common - typos and grammar errors are almost the rule in
some places. Many developers seem to (rightly IMHO) prioritize the
quality of UI messages, and give schemas messages little to no attention
of the same kind. But this on the other hand causes problems for
translators, for whom there's little difference between UI messages and
schemas messages - they are all translated in the same domain, so they
all need to use the same proper terminology and be spellchecked for
efficient translation. Example reports are #115693 and #115746.

3) is rather common in some places. In many applications, there's one
terminology used in the UI and another one used in the code. Nothing
wrong with that, but the problem is that when schemas messages are
written, they sometimes use the terminology from the code. Translators
then need to fiddle with two different sets of terminologies. Slang is
also common. Example reports are #115570 and #113380.

4) is a not uncommon problem, both for translators and potentially also
for users. In gconf keys, the possible values for keys are often literal
strings, and they are listed in the messages, but not always enclosed in
double quotes. Thus it can be hard to know that they are literal values,
and the danger of accidental translation is very high. In other words,
schemas messages sometimes look like this:
	'Possible values are on_top, left and right.'
While they should be written:
	'Possible values are "on_top", "left" and "right".'
Example reports are #100278 and #115743.

5) Sometimes the descriptions are not properly maintained, and stay the
same even if the meaning of the key changes. Example report is #114584.


A more or less de facto style seems to have developed for most schemas
messages, and in the guidelines below I try to summarize those, all for
the sake of consistency:

a) All schemas descriptions should start with an uppercase letter.
b) <short> descriptions should NOT end in a period.
c) <long> descriptions SHOULD end in a period.
d) Literal key values should always be enclosed in double quotes when
referred to.
e) Make the descriptions consistent with other descriptions in the same
module.
f) Use the same terminology as in the UI if possible. Specifically, do
never use slang in the descriptions, and don't use terminology only used
in the code if possible.
g) Check the spelling of the messages.
h) Don't use "If ..." but rather "Whether ...", if possible, as the
start of <long> descriptions.
i) Make sure you have both <short> and useful <long> descriptions for
all keys, for the benefit of the users.
j) Once in a while, make sure the descriptions are still valid(!)


Christian