Localisation - User messages in LilyPond
****************************************

Introduction
============

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 (In addition to the C++ coding standards that come with Lily).  Hopefully, this can be replaced by general GNU guidelines in the future.

Not-preferred messages are marked with +. By convention, agrammatical examples are marked with *.

Guidelines
==========

  * Every message to the user should be localised (and thus be marked for localisation).  This includes warning and error messages.

  * Don't localise/gettextify:

       - programming_error ()s

       - programming_warning ()s

       - debug strings

       - output strings (PostScript, TeX) (This may seem ridiculously obvious, however, makeinfo-3.12s localises output strings.  Sending bug report now ---jcn)

  * Messages to be localised must be encapsulated in _ (STRING) or _f (FORMAT, ...).  Eg:

          warning (_ ("Need music in a score"));
          error (_f ("Can't open file: `%s'", file_name));

     In some rare cases you may need to call 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 _i (STRING).  The _i macro is a no-op, it only serves as a marker for xgettext.

          char const* messages[] = {
            _i ("enable debugging output"),
            _i ("ignore mudela version"),
            0
          };

          void
          foo (int i)
          {
            puts (gettext (messages [i]));
          }

     See also flower/getopt-long.cc and lily/main.cc.

  * Don't use leading or trailing whitespace in messages.

  * Messages containing a final verb, or a gerund (-ing-form) always start with a capital.  Other (simpler) messages start with a lowercase letter:

          The word `foo' is not declared.
          `foo': not declared.
          Not declaring: `foo'.

  * To avoid having a number of different messages for the same situation, we'll use quoting like this "message: `%s'" for all strings. Numbers are not quoted:

          _f ("Can't open file: `%s'", name_str)
          _f ("Can't find charater number: %d", i)

  * Think about translation issues. 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

          _ ("Stem at ") + moment.str () + _(" doen't fit in beam")

     have

          _f ("Stem at %s doen't fit in beam", moment.str ())

  * Split up multi-sentence messages, whenever possible.  Instead of

          warning (_f ("out of tune!  Can't find: `%s', "Key_engraver"));

          warning (_f ("Can't find font `%s', loading default",
                       font_name));

     rather say:

          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"));

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

             _f ("Non-matching braces in text `%s', adding braces", text)
             _ ("Debug output disabled.  Compiled with NPRINT.")
             _f ("Huh?  Not a Request: `%s'.  Ignoring.", request)

  * Don't modularise too much; a lot of words cannot be translated without context. It's probably safe to treat most occurences of words like stem, beam, crescendo as separately translatable words.

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

              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)

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

  * Please don't run make po/po-update with GNU gettext < 0.10.35