@chapter Localisation - User messages in LilyPond
-@section ISSUES
+@section Introduction
-The current default is marked with @code{+}.
+This document provides some guidelines for uniformising user messages.
+In the absence of other standards, we'll be using these rules when coding
+for for LilyPond@footnote{
+In addition to the C++ coding standards that come with Lily
+}. Hopefully, this can be replaced by general GNU
+guidelines in the future.
-@itemize @bullet
-
-@item
-How to do two-part messages like these? Better spread over multiple lines?
-@example
- warning (_f ("out of tune! Can't find: `%s\', "Key_engraver"));
-or
-+ warning (_ ("out of tune:");
- warning (_f ("Can't find: `%s\', "Key_engraver"));
-
- warning (_f ("Can't find font `%s', loading default font", name.ch_C ()));
-or
-+ warning (_f ("Can't find font: `%s', name.ch_C ()));
- warning (_f ("Loading default font"));
-@end example
-
-@item
-How to do messages with punctuation:
-@example
-Logical:
-+ warning ( _("Huh? Not a Request: `%s'", s);
-Guidelines say:
- warning ( _("huh? not a Request: `%s'", s);
-@end example
-
-@item
-No punctuation (esp. period) at end of message.
-
-But what about multiple-sentence, or full-sentence (including other
-punctuation) messages?
-@example
-+ _ ("Debug output disabled. Compiled with NPRINT.")
-+ _ ("Non-matching braces in text `%s', adding braces")
-@end example
-
-@item
-@example
- en: can't open: `foo.ly'
- nl: kan `foo.ly' niet openen (1)
-+ kan niet openen: `foo.ly'* (2)
- niet te openen: `foo.ly'* (3)
-@end example
-
-The first nl message, although gramatically and stylishly correct,
-is not friendly for parsing by humans (even if they speak dutch).
-I guess we'd prefer something like (2) or (3)...
-
-@end itemize
+Not-preferred messages are marked with @code{+}.
+By convention, agrammatical examples are marked with @code{*}.
@section Guidelines
@itemize @bullet
@item
-Every user message should be localised.
+Every message to the user should be localised (and thus be marked
+for localisation). This includes warning and error messages.
@item
Don't localise/gettextify:
+
@itemize @minus
@item @code{programming_error ()}s
@item @code{programming_warning ()}s
@item debug strings
-@item output strings (PostScript, TeX)
+@item output strings (PostScript, TeX)@footnote{
+This may seem ridiculously obvious, however, makeinfo-3.12s localises
+output strings. Sending bug report now ---jcn
+}
@end itemize
+
+
@item
-Strings to be localised must be encapsulated in @code{_ (STRING)}
+Messages to be localised must be encapsulated in @code{_ (STRING)}
or @code{_f (FORMAT, ...)}. Eg:
+
@example
warning (_ ("Need music in a score"));
-error (_f ("Can't open file: `%s'"));
+error (_f ("Can't open file: `%s'", file_name));
@end example
-Only in very rare cases you may need to call @code{gettext ()} by hand.
-In that case, you'll probably also need to mark some string constants for
-translation, using @code{_i (STRING)}. See @file{flower/getopt-long.cc}
-and @file{lily/main.cc}.
+In some rare cases you may need to call @code{gettext ()} by hand.
+This happens when you pre-define (a list of) string constants for later
+use. In that case, you'll probably also need to mark these string
+constants for translation, using @code{_i (STRING)}. The @code{_i}
+macro is a no-op, it only serves as a marker for @file{xgettext}.
+
+@example
+char const* messages[] = @{
+ _i ("enable debugging output"),
+ _i ("ignore mudela version"),
+ 0
+@};
+
+void
+foo (int i)
+@{
+ puts (gettext (messages [i]));
+@}
+@end example
+
+See also
+@file{flower/getopt-long.cc} and @file{lily/main.cc}.
@item
-Don't use leading or trailing whitespace in strings.
+Don't use leading or trailing whitespace in messages.
@item
Messages containing a final verb, or a gerund (@code{-ing}-form)
always start with a capital. Other (simpler) messages start with
a lowercase letter:
+
@example
The word `foo' is not declared.
`foo': not declared.
To avoid having a number of different messages for the same situation,
we'll use quoting like this @code{"message: `%s'"} for all strings.
Numbers are not quoted:
+
@example
_f ("Can't open file: `%s'", name_str)
_f ("Can't find charater number: %d", i)
In a lot of cases,it's better to translate a whole message.
The english grammar mustn't be imposed on the translator.
So, iso
+
@example
_ ("Stem at ") + moment.str () + _(" doen't fit in beam")
@end example
+
@noindent
have
+
@example
_f ("Stem at %s doen't fit in beam", moment.str ())
@end example
@item
-Use two spaces after end of sentence punctuation:
+Split up multi-sentence messages, whenever possible. Instead of
+
+@example
+warning (_f ("out of tune! Can't find: `%s', "Key_engraver"));
+
+warning (_f ("Can't find font `%s', loading default",
+ font_name));
+@end example
+
+@noindent
+rather say:
+
+@example
+warning (_ ("out of tune:");
+warning (_f ("Can't find: `%s', "Key_engraver"));
+
+warning (_f ("Can't find font: `%s', font_name));
+warning (_f ("Loading default font"));
+@end example
+
+@item
+If you must have multiple-sentence messages, use full punctuation.
+Use two spaces after end of sentence punctuation.
+No punctuation (esp. period) is used at the end of simple messages.
+
@example
-_ ("Huh? Not a Request")
+ _f ("Non-matching braces in text `%s', adding braces", text)
+ _ ("Debug output disabled. Compiled with NPRINT.")
+ _f ("Huh? Not a Request: `%s'. Ignoring.", request)
@end example
@item
It's probably safe to treat most occurences of words like
stem, beam, crescendo as separately translatable words.
+@item
+When translating, it is preferrable to put interesting information
+at the end of the message, rather than embedded in the middle.
+This especially applies to frequently used messages, even if this
+would mean sacrificing a bit of eloquency. This holds for original
+messages too, of course.
+
+@example
+ en: can't open: `foo.ly'
++ nl: kan `foo.ly' niet openen (1)
+ kan niet openen: `foo.ly'* (2)
+ niet te openen: `foo.ly'* (3)
+@end example
+
+The first nl message, although gramatically and stylishly correct,
+is not friendly for parsing by humans (even if they speak dutch).
+I guess we'd prefer something like (2) or (3).
+
@item
Please don't run make po/po-update with GNU gettext < 0.10.35
projects / lilypond.git / commitdiff