Documentation/Localisation.texi

   1 \input texinfo @c -*-texinfo-*- vim:tw=72
   2 @setfilename Localisation
   3 @settitle Localisation - User messages in LilyPond
   4
   5 @node Top, , , (dir)
   6 @top
   7
   8 @chapter Localisation - User messages in LilyPond
   9
  10 @section Introduction
  11
  12 This document provides some guidelines for uniformising user messages.
  13 In the absence of other standards, we'll be using these rules when coding
  14 for for LilyPond@footnote{
  15 In addition to the C++ coding standards that come with Lily
  16 }.  Hopefully, this can be replaced by general GNU
  17 guidelines in the future.
  18
  19 Not-preferred messages are marked with @code{+}.
  20 By convention, agrammatical examples are marked with @code{*}.
  21
  22
  23 @section Guidelines
  24
  25 @itemize @bullet
  26
  27 @item
  28 Every message to the user should be localised (and thus be marked
  29 for localisation).  This includes warning and error messages.
  30
  31 @item
  32 Don't localise/gettextify:
  33
  34 @itemize @minus
  35 @item @code{programming_error ()}s
  36 @item @code{programming_warning ()}s
  37 @item debug strings
  38 @item output strings (PostScript, TeX)@footnote{
  39 This may seem ridiculously obvious, however, makeinfo-3.12s localises
  40 output strings.  Sending bug report now ---jcn
  41 }
  42 @end itemize
  43
  44
  45
  46 @item
  47 Messages to be localised must be encapsulated in @code{_ (STRING)}
  48 or @code{_f (FORMAT, ...)}.  Eg:
  49
  50 @example
  51 warning (_ ("Need music in a score"));
  52 error (_f ("Can't open file: `%s'", file_name));
  53 @end example
  54
  55 In some rare cases you may need to call @code{gettext ()} by hand.
  56 This happens when you pre-define (a list of) string constants for later
  57 use.  In that case, you'll probably also need to mark these string
  58 constants for translation, using @code{_i (STRING)}.  The @code{_i}
  59 macro is a no-op, it only serves as a marker for @file{xgettext}.
  60
  61 @example
  62 char const* messages[] = @{
  63   _i ("enable debugging output"),
  64   _i ("ignore mudela version"),
  65   0
  66 @};
  67
  68 void
  69 foo (int i)
  70 @{
  71   puts (gettext (messages [i]));
  72 @}
  73 @end example
  74
  75 See also
  76 @file{flower/getopt-long.cc} and @file{lily/main.cc}.
  77
  78 @item
  79 Don't use leading or trailing whitespace in messages.
  80
  81 @item
  82 Messages containing a final verb, or a gerund (@code{-ing}-form)
  83 always start with a capital.  Other (simpler) messages start with
  84 a lowercase letter:
  85
  86 @example
  87 The word `foo' is not declared.
  88 `foo': not declared.
  89 Not declaring: `foo'.
  90 @end example
  91
  92 @item
  93 To avoid having a number of different messages for the same situation,
  94 we'll use quoting like this @code{"message: `%s'"} for all strings.
  95 Numbers are not quoted:
  96
  97 @example
  98 _f ("Can't open file: `%s'", name_str)
  99 _f ("Can't find charater number: %d", i)
 100 @end example
 101
 102 @item
 103 Think about translation issues.
 104 In a lot of cases,it's better to translate a whole message.
 105 The english grammar mustn't be imposed on the translator.
 106 So, iso
 107
 108 @example
 109 _ ("Stem at ") + moment.str () + _(" doen't fit in beam")
 110 @end example
 111
 112 @noindent
 113 have
 114
 115 @example
 116 _f ("Stem at %s doen't fit in beam", moment.str ())
 117 @end example
 118
 119 @item
 120 Split up multi-sentence messages, whenever possible.  Instead of
 121
 122 @example
 123 warning (_f ("out of tune!  Can't find: `%s', "Key_engraver"));
 124
 125 warning (_f ("Can't find font `%s', loading default",
 126              font_name));
 127 @end example
 128
 129 @noindent
 130 rather say:
 131
 132 @example
 133 warning (_ ("out of tune:");
 134 warning (_f ("Can't find: `%s', "Key_engraver"));
 135
 136 warning (_f ("Can't find font: `%s', font_name));
 137 warning (_f ("Loading default font"));
 138 @end example
 139
 140 @item
 141 If you must have multiple-sentence messages, use full punctuation.
 142 Use two spaces after end of sentence punctuation.
 143 No punctuation (esp. period) is used at the end of simple messages.
 144
 145 @example
 146    _f ("Non-matching braces in text `%s', adding braces", text)
 147    _ ("Debug output disabled.  Compiled with NPRINT.")
 148    _f ("Huh?  Not a Request: `%s'.  Ignoring.", request)
 149 @end example
 150
 151 @item
 152 Don't modularise too much; a lot of words cannot be translated
 153 without context.
 154 It's probably safe to treat most occurences of words like
 155 stem, beam, crescendo as separately translatable words.
 156
 157 @item
 158 When translating, it is preferrable to put interesting information
 159 at the end of the message, rather than embedded in the middle.
 160 This especially applies to frequently used messages, even if this
 161 would mean sacrificing a bit of eloquency.  This holds for original
 162 messages too, of course.
 163
 164 @example
 165     en: can't open: `foo.ly'
 166 +   nl: kan `foo.ly' niet openen (1)
 167     kan niet openen: `foo.ly'*   (2)
 168     niet te openen: `foo.ly'*    (3)
 169 @end example
 170
 171 The first nl message, although gramatically and stylishly correct,
 172 is not friendly for parsing by humans (even if they speak dutch).
 173 I guess we'd prefer something like (2) or (3).
 174
 175 @item
 176 Please don't run make po/po-update with GNU gettext < 0.10.35
 177
 178 @end itemize
 179
 180 @bye