10.5.8 Localization

This document provides some guidelines to help programmers write proper user messages. To help translations, user messages must follow uniform conventions. Follow these rules when coding for LilyPond. Hopefully, this can be replaced by general GNU guidelines in the future. Even better would be to have an English (en_GB, en_US) guide helping programmers writing consistent messages for all GNU programs.

Non-preferred messages are marked with ‘+’. By convention, ungrammatical examples are marked with ‘*’. However, such ungrammatical examples may still be preferred.

• Every message to the user should be localized (and thus be marked for localization). This includes warning and error messages.
• Do not localize/gettextify:
  • programming_error
  • programming_warning
  • debug strings
  • output strings (PostScript, TeX, etc.)
• Messages to be localized must be encapsulated in _ (string) or _f (format, ...), for example

  warning (_ ("need music in a score"));
  error (_f ("cannot 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 lilypond version"),
    0
  };
  
  void
  foo (int i)
  {
    puts (gettext (messages i));
  }
  

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

• Do not use leading or trailing whitespace in messages. If you need whitespace to be printed, prepend or append it to the translated message

  message ("Calculating line breaks..." + " ");
  

• Error or warning messages displayed with a file name and line number never start with a capital, eg,

  foo.ly: 12: not a duration: 3
  

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

  Processing foo.ly...
  `foo': not declared.
  Not declaring: `foo'.
  

• Avoid abbreviations or short forms, use ‘cannot’ and ‘do not’ rather than ‘can’t’ or ‘don’t’ To avoid having a number of different messages for the same situation, we will use quoting like this "message: `%s'" for all strings. Numbers are not quoted:

  _f ("cannot open file: `%s'", name_str)
  _f ("cannot find character number: %d", i)
  

• Think about translation issues. In a lot of cases, it is better to translate a whole message. English grammar must not be imposed on the translator. So, instead of

  stem at  + moment.str () +  does not fit in beam
  

  have

  _f ("stem at %s does not 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 ("cannot find font `%s', loading default", font_name));
  

  rather say:

  warning (_ ("out of tune:"));
  warning (_f ("cannot find: `%s', "Key_engraver"));
  warning (_f ("cannot 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)
  

• Do not modularize too much; words frequently cannot be translated without context. It is probably safe to treat most occurrences of words like stem, beam, crescendo as separately translatable words.
• When translating, it is preferable 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 eloquence. This holds for original messages too, of course.

  en: cannot 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 grammatically and stylistically correct, is not friendly for parsing by humans (even if they speak dutch). I guess we would prefer something like (2) or (3).

• Do not run make po/po-update with GNU gettext < 0.10.35