UI Text Conventions

h1. UI Text Conventions

Guidelines

The points listed below help you to make sure the text strings presented to the user are easy to handle by interpreters for localized applications. One should basically keep in mind that user interface text strings (enclosed in tr()-calls) are potentially extracted from of the source code in the translation process and thus the interpreter does not necessarily know the source code context of the messages.

• Add linguist comments ( //:) to clarify where appropriate:

//: Contact book "Add person" button label<br />return tr("Add");<br />

• If the class is not a Q_OBJECT, use

  QCoreApplication::translate("class context", "message")<code> or consider using <code>Q_DECLARE_TR_FUNCTIONS<code>
  
  * Do not use
  

  QObject::tr() which is confusing since the messages appear grouped by class context in linguist, which messages tied to QObject do not have.

• Avoid contractions and do not shout at users using exclamation marks:

  tr("Cannot open the file.")<code> instead of<br />
  

  tr("Can't open the file!")

• Use plurals correctly:

  tr("%n files found", 0, number)<code> instead of <code>tr("%1 files found").arg(number)<code> 
  
  * Be aware that articles have a grammatical gender in some languages and sentences cannot be as easily constructed as in English, so avoid things like:
  

  tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")

• Try to avoid concatenating messages (use "%1" formatting instead), as some constructions may not work for grammar reasons. Also, never use leading/trailing/multiple blanks to achieve formatting in a message, as they will invariably be clobbered by translators (think Excel, other tools):

  tr("Foo failed: %1").arg(message)<code> instead of <code>tr("Foo failed: ") + message<code>
  
  * In Qt Designer, preferably use plain text for Tooltips. Should you want some extra formatting, write short, canonical HTML in the source tab of the rich text editor:
  

  <html&amp;gt;<head/><body&amp;gt;Note: text. In Qt 4.7, only the source tab of the Designer rich text editor should be used. The automatic conversion performed by the rich text editor tab produces a lot of redundant stylesheet information and hard-coded fonts that look bad on other platforms and make translation in Linguist difficult. Qt Designer 4.8 has a feature simplifying the rich text (on by default), still, you should verify by looking at the source tab.

• We follow the "Capitalization Guidelines of the KDE Project":http://developer.kde.org/documentation/standards/kde/style/basics/labels.html#items

Capitalization Guides Short Reference

Here is a short summary of the above mentioned Capitalization Guidelines. Two major styles are used, book title and sentence style:

• Example of Book Title Capitalization
• Example of sentence style capitalization

Use book style for:
* Titles (window, dialog, group box, tab, list view columns, and so on)
* Functions (menu items, buttons)
* Selectable items (combobox items, listbox items, tree list items, and so on)

Use sentence style for:
* Labels
* Tool tips
* Descriptive text