Don't use too long messages

Long messages, that span several paragraphs like the following message, are very difficult to translate.

   msgid ""
   "Pv\n"
   "\n"
   "Present value\n"
   "\n"
   "Keyboard equivalent:   p\n"
   "\n"
   "Determines the present value of an investment. It\n"
   "computes the present value based on a series of\n"
   "equal payments, each of amount pmt, discounted at\n"
   "periodic interest rate int, over the number of\n"
   "periods in term.\n"
   "\n"
   "Memory register usage:\n"
   "\n"
   "   Register 0 - pmt (periodic payment)\n"
   "   Register 1 - int (periodic interest rate)\n"
   "   Register 2 - n   (term)\n"
   "\n"
   "Example:\n"
   "\n"
   "You have just won a million dollars. The prize\n"
   "is awarded in 20 annual payments of $50,000 each\n"
   "(a total of $1,000,000 over 20 years). Annual\n"
   "payments are received at the end of each year.\n"
   "\n"
   "You are given the option of receiving a single\n"
   "lump-sum payment of $400,000 instead of the\n"
   "million dollars annuity. You want to find out\n"
   "which option is worth more in today's dollars.\n"
   "\n"
   "If you were to accept the annual payments of\n"
   "$50,000, you assume that you would invest the\n"
   "money at a rate of 9%, compounded annually.\n"
   "\n"
   "Memory register usage:\n"
   "\n"
   "   Register 0 - 50000 (periodic payment).\n"
   "   Register 1 - 0.09  (periodic interest rate\n"
   "                       is 9%)\n"
   "   Register 2 - 20    (term)\n"
   "\n"
   "Clicking SELECT on Pv returns a value of\n"
   "456427.28, which tells you that the $1,000,000\n"
   "paid over 20 years is worth $456,427.28 in\n"
   "present dollars.\n"
   "\n"
   "Based on your assumptions, the lump-sum\n"
   "payment of $400,000 is worth less than the\n"
   "million-dollar ordinary annuity, in present\n"
   "dollars (before taxes)."

Part of this difficulty is because doing translations require both the msgid (the original message) and the msgstr (the translation) to be visible at the same time. Very long messages make that harder, since significant scrolling or additional windows are needed.

Worse is that very long messages break the easy spotting of changes that the translators depend upon when updating the translations of changed messages. Gettext uses "fuzzy marking" to mark messages that have changed, but doesn't mark what part of the message changed. In most cases this is no problem, a simple visual comparison by a trained eye between the existing translation and the new message is well enough to spot the difference and update the translation accordingly.

But this gets increasingly harder the longer the message is. With several paragraphs of text in a single message, or even several pages, it's close to impossible to do this visual comparison to spot changes, changes that may even be as small as a fixed typo anywhere in the message, or for example a removed whitespace or added point.

A useful rule is to keep the message size at the size of a paragraph at most. If the text is several paragraphs, split the message into several messages, each consisting of one paragraph.

TranslationProject/DevGuidelines/Don't use too long messages (last edited 2008-02-03 14:44:39 by localhost)