UI Text Conventions: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Decode HTML entity names)
(Formatting)
 
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}


= UI Text Conventions =
== Guidelines ==
== Guidelines ==


Line 7: Line 5:


* Add linguist comments ( //:) to clarify where appropriate:
* Add linguist comments ( //:) to clarify where appropriate:
<code>//: Contact book "Add person" button label
<code>//: Contact book "Add person" button label
return tr("Add");
return tr("Add");
</code>
</code>


* If the class is not a Q_OBJECT, use <code>QCoreApplication::translate("class context", "message")<code> or consider using <code>Q_DECLARE_TR_FUNCTIONS<code>
* If the class is not a Q_OBJECT, use  
<code>QCoreApplication::translate("class context", "message")</code>  
or consider using  
<code>Q_DECLARE_TR_FUNCTIONS</code>


* Do not use </code>QObject::tr()</code> which is confusing since the messages appear grouped by class context in linguist, which messages tied to QObject do not have.
* 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: <code>tr("Cannot open the file.")<code> instead of
* Avoid contractions and do not shout at users using exclamation marks:  
</code>tr("Can't open the file!")</code>
<code>tr("Cannot open the file.")</code>  
instead of  
<code>tr("Can't open the file!")</code>


* Use plurals correctly: <code>tr("%n files found", 0, number)<code> instead of <code>tr("%1 files found").arg(number)<code>  
* Use plurals correctly:  
<code>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: </code>tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")</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:  
<code>tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")</code>


* 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): <code>tr("Foo failed: %1").arg(message)<code> instead of <code>tr("Foo failed: ") + message<code>
* 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):  
<code>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: </code><html><head/><body><b>Note:</b> text.</code> 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.
* 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:  
<code><html><head/><body><b>Note:</b> text.</code>
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 [http://developer.kde.org/documentation/standards/kde/style/basics/labels.html#items Capitalization Guidelines of the KDE Project]
* We follow the [http://developer.kde.org/documentation/standards/kde/style/basics/labels.html#items Capitalization Guidelines of the KDE Project]

Latest revision as of 10:25, 9 April 2015

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
return tr("Add");
  • If the class is not a Q_OBJECT, use
QCoreApplication::translate("class context", "message")

or consider using 

Q_DECLARE_TR_FUNCTIONS
  • 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.")

instead of 

tr("Can't open the file!")
  • Use plurals correctly:
tr("%n files found", 0, number)

instead of 

tr("%1 files found").arg(number)
  • 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)

instead of 

tr("Foo failed: ") + message
  • 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><head/><body><b>Note:</b> 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.

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
Retrieved from "https://wiki.qt.io/index.php?title=UI_Text_Conventions&oldid=15547"