UI Text Conventions: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
Henri Vikki (talk | contribs) (Formatting) |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
==Guidelines== | == 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. | 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: | * Add linguist comments ( //:) to clarify where appropriate: | ||
<code>//: Contact book "Add person" button label | |||
return tr("Add"); | |||
</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> | |||
==Capitalization Guides Short Reference== | * 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 | |||
<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> | |||
* 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> | |||
* 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] | |||
== 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: | Here is a short summary of the above mentioned Capitalization Guidelines. Two major styles are used, book title and sentence style: | ||
| Line 17: | Line 48: | ||
Use book style for: | Use book style for: | ||
* Titles (window, dialog, group box, tab, list view columns, and so on) | * Titles (window, dialog, group box, tab, list view columns, and so on) | ||
* Functions (menu items, buttons) | * Functions (menu items, buttons) | ||
| Line 23: | Line 53: | ||
Use sentence style for: | Use sentence style for: | ||
* Labels | * Labels | ||
* Tool tips | * Tool tips | ||
* Descriptive text | * Descriptive text | ||
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.
- We follow the Capitalization Guidelines of the KDE Project
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