Index: alphabet.xml.in
===================================================================
RCS file: /cvs/gnome/gok/alphabet.xml.in,v
retrieving revision 1.1
diff -u -r1.1 alphabet.xml.in
--- alphabet.xml.in	1 Jul 2003 19:17:17 -0000	1.1
+++ alphabet.xml.in	7 Jun 2004 17:24:25 -0000
@@ -2,10 +2,39 @@
 <GOK:GokFile xmlns:GOK="http://www.gnome.org/GOK">
 
 <GOK:charset>
+
+	<!-- Note to Translators: the following strings should contain your LANG/locale's 
+	 alphabet or, in the case of LANGs with a very large glyph set, a set of
+	 character-primitives which can be used to compose your language's character set.
+	 Each string below corresponds to the characters associated with a particular
+	 "shift level" in the XKB keyboard definition.
+	 The prefix before the '|' character is just a context string and need not be
+	 translated.
+	 
+	 For languages where 'case' is used, the first string should contain 
+	 the lowercase alphabet. 
+	 
+	 Note that unless your locale clearly requires that digits and/or punctuation
+	 precede alphabetic characters, digits and punctuation should be placed 
+	 at the end of the string. -->
 	<_GOK:alpha level="0">abcdefghijklmnopqrstuvwxyz</_GOK:alpha>
+
+	<!-- The substring "level 1|" should not be translated.
+	 For languages/locales which use 'upper case', this string should 
+	 correspond to uppercase versions of characters in the 'level 0' string. -->
 	<_GOK:alpha level="1">ABCDEFGHIJKLMNOPQRSTUVWXYZ</_GOK:alpha>
+
+	<!-- Not used in C locale: this string can contain a third set of characters
+	at another 'shift level'.  It can be used to provide a second/alternate
+	glyph/character set for the locale, separately or in conjunction with
+	'level 3'.  At the translator's discretion, accented characters can be
+	placed here and in 'level 3' as well. -->
 	<_GOK:alpha level="2">æ”¢ðeđŋħ→jĸłµnøþ@¶ßŧ↓“ł»←«</_GOK:alpha>
+	
+	<!-- For locales which need an even larger character set, or offer uppercase versions
+	 of the 'level2' characters, add them to 'level 3' -->
 	<_GOK:alpha level="3">Æ'©ÐEªŊĦıJ&amp;ŁºNØÞΩ®§Ŧ↑`Ł&gt;¥&lt;</_GOK:alpha>
+
 	<_GOK:levels>"Shift AltGr Level-3"</_GOK:levels>
 	<_GOK:spacebar>"spacebar"</_GOK:spacebar>
 	<_GOK:tab>"Tab"</_GOK:tab>
