Commit 1cedb84b authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Doc: initial draft of UI text guidelines

parent 583c848a
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/
/*!
\contentspage{index.html}{Qt Creator}
\previouspage external-tool-spec.html
\page qtcreator-ui-text.html
\nextpage coding-style.html
\title User Interface Text Guidelines
Follow the guidelines in this section to make sure that your extensions
are consistent with the Qt Creator UI and that they can be easily
localized into different languages.
When you write UI text, make sure that it is:
\list
\o Consistent with existing Qt Creator UI terms
\o Short and concise
\o Neutral, descriptive, and factually correct
\o Unambigious
\o Translatable into different languages
\endlist
\section1 Grammar and Style
All UI text must be grammatically correct English and use the standard form
of written language. Do not use dialect or slang words. Use idiomatic
language, that is, expressions that are characteristic for English.
If possible, ask a native English speaker for a review.
UI text should be concise and economically formulated. Avoid unnecessary
content words and phrases. The following message contains unnecessary
content: \e {Do you want to delete this document?}. It could be rephrased
as: \e {Delete document?}.
Avoid addressing the user in the second person. Use a neutral tone or
passive voice but use a formal address when necessary. Avoid using the
word \e Please when addressing the user. Exceptions to this are some
copyright text and short imperative sentences that might otherwise sound
abrupt. For example, \e {Please wait.}
Avoid abbreviations in the menu names and items. If there is no room for
the full spelling or hyphenation of a word, abbreviate the text according
to the English abbreviation rules.
Avoid contractions. For example, write \e cannot instead of \e can't.
\section1 Punctuation
Avoid using punctuation marks or special characters in menu names and
items.
Use punctuation marks as follows:
\list
\o Never user full stops (.) at the end of menu item names.
\o Use full stops in messages.
\o Use exclamation marks (!) only in text that demands extra attention
from the user or carries special weight.
\o Use quotation marks ("") around variable values. For example,
\gui {Close Project "qtcreator"}.
\o Do not use leading, trailing, or multiple spaces to align text in
messages, as translation tools might not handle them correctly.
\endlist
\section2 Writing Tooltips
Tooltips contain useful information about icons, menu items, or other UI
elements. They appear when users place the mouse pointer over an UI
element. You can also add descriptive text to the UI that is always
visible.
For an icon, you can use the command name as a tool tip. In that
case, use book style capitalization and do not add a comma after the tool
tip.
\image qtcreator-tooltip.png "Tooltip"
Tooltips can also contain full sentences. Try to make them as short and
concise as possible, while still making them grammatically correct. Use
sentence style capitalization and punctuation as you would for any
sentence.
\image qtcreator-tooltip-long.png "Sentence as a tooltip"
\section3 Writing Tooltips in Design Mode
In Qt Designer, use plain text for tooltips. For extra formatting, write
short, canonical HTML in the source tab of the rich text editor:
\c {<html><head/><body><b>Note:</b> text.}
In Qt 4.7, use only the \gui Source tab of the Qt Designer rich text
editor. The automatic conversion performed by the rich text editor tab
generates a lot of redundant stylesheet information and uses hard-coded
fonts that look bad on other platforms and make translation in Qt Linguist
difficult.
Qt Designer 4.8 has a feature that simplifies the rich text (on by
default), but still, you should verify by looking at the \gui Source tab.
\section2 Writing Messages
Check that messages are concise and economically formulated. Avoid
excessive use of, for example, verbs and articles if the sentence is
grammatically correct without them, such as:
\list
\o SIM card full (NOT: SIM card is full)
\o Calendar entry deleted (NOT: Calendar entry has been deleted)
\endlist
Keep the use of many new and different sentence structures to a minimum.
Reuse sentence structures that have been used in similar situations. For
example:
\list
\o Cannot send log as selected message type. Text too long.
\o Cannot receive image.
\o Cannot insert picture. Maximum text length is 120 characters.
\o Image name already in use.
\o Folder name already in use.
\endlist
\section1 UI Text Capitalization
The capitalization of the Qt Creator UI text follows the
\l{http://developer.kde.org/documentation/standards/kde/style/basics/labels.html#items}
{KDE Style Guide}.
Two styles are used, book title and sentence style:
\list
\o Example of Book Title Capitalization
\o Example of sentence style capitalization
\endlist
Use book style capitalization for:
\list
\o Titles (window, dialog, group box, tab, list view columns, and so
on)
\o Functions (menu items, buttons)
\o Selectable items (combobox items, listbox items, tree list items,
and so on)
\endlist
Use sentence style capitalization for:
\list
\o Labels
\o Tool tips
\o Descriptive text
\o Other non-heading or title text
\endlist
\section1 Preparing for Localization
Qt Creator is localized into several languages. Consistency and conciseness
make UI text easier to translate.
\section2 Marking UI Text for Translation
Make sure the text strings presented to the user are easy to translate.
The user interface text strings are enclosed in \c tr() calls and
extracted from the source code during the translation process. Therefore,
the translator might not know the source code context of the messages.
You can add comments that are visible in Qt Linguist ( //:) to clarify the
context. For example:
\code
//: Contact book "Add person" button label
return tr("Add");
\endcode
If the class is not Q_OBJECT, use \c {QCoreApplication::translate("class
context", "message")} or consider using Q_DECLARE_TR_FUNCTIONS. Do not use
\c {QObject::tr()}, which is confusing because the messages appear grouped
by class context in Qt Linguist and messages tied to QObject do not have a
class context.
\section2 Features of Languages or Writing Systems
To allow for localization of your extensions, consider the impact that
languages and writing systems have on the implementation.
\table
\header
\o Features of Languages or Writing Systems
\o Impact on Implementation
\row
\o Word order
\o Different languages have different word order rules.
Do not use run-time concatenation. Use complete phrases
and “%1” formatting instead. For example, use:
\c{tr("Foo failed: %1").arg(message)}
instead of
\c {tr("Foo failed: ") + message}
\row
\o Singular vs. plural vs. dual forms
\o Some languages do not have plural form (for example, Chinese
and Japanese), whereas some have a different form for dual.
Allow room for text expansion in the layout design. Some
languages need more space to indicate plurality or duality to
convey the needed information.
For example, use
\c {tr("%n files found", 0, number)}
instead of
\c {tr("%1 files found").arg(number)}
\row
\o Gender
\o Some languages have gender (feminine, masculine, neutral),
whereas some do not (for example, Finnish) or do not use it
extensively (for example, English).
Do not reuse text strings. The same term may not work in
another context due to the gender of the base word.
Articles have a grammatical gender in some languages and
sentences cannot be as easily constructed as in English. Avoid
following types of constructs:
\c {tr("%1 failed").arg(someCondition ? "the operation" : "opening a file")}
\row
\o Compound words
\o Some languages form new words by combining existing words into
new compound words (for example, Finnish and Thai).
Allow for text expansion. The compound words tend to make terms
longer than in English.
\row
\o Word boundaries
\o There are languages that do not use space as word boundaries
(for example, Thai, also Chinese and Japanese to some extent).
Use the line wrapping function.
\row
\o Abbreviations
\o There are languages that do not allow abbreviating words, (for
example, Chinese, Arabic).
Do not assume that all supported languages can be abbreviated
if the layout is not wide enough.
\row
\o Length of words
\o Most languages have longer words than English.
Do not assume that the layout is OK if a short English word
fits in.
\row
\o Direction of text flow
\o In Qt Creator, both left-to-right and right-to-left text flow
is supported.
Arabic and Hebrew writing systems are essentially
bidirectional, that is, the text can flow either from right to
left or vice versa, depending on the characters' attributes.
\row
\o Writing systems
\o Qt widgets embed most of the writing system support.
Do not assume a certain character is always available in
every language and every writing system.
Allow for different directions in text flow (unless
feature-related standard dictates differently). For example,
allow for the bidirectionality of Arabic script.
Do not assume that if your software functions properly in
English, it will be OK also in other languages and writing
systems.
\row
\o Character sets and character repertoire
\o Do not assume a certain character is always available.
\row
\o Multiple scripts within one writing system for one language
\o Do not assume that a language would use only one script in
writing.
\row
\o Digits
\o Allow also for other than European digits (1,2,3, ...).
\endtable
\section1 Common Qt Creator Terms
This section summarizes the terminology used for common Qt Creator UI
components. It also describes the conventions for naming different types of
UI components.
Always check that the term you plan to use is not used to mean something
else in the UI. If a suitable term already exists, use it. For example, use
\e Find for searching and \e New for wizards that create new objects.
For more information on how to add UI components, see
\l{Common Extension Tasks}.
\table
\header
\o UI Text
\o Usage
\o Conventions
\row
\o Context menu
\o Opens when users right-click on the screen. Contents depend on
the context.
\image qtcreator-context-menu.png "Context menu"
\o You can add menu items that are relevant in a particular
context. Follow the conventions for naming menu items.
\row
\o Dialog
\o User interface element that usually contains a number of
choices or allows the user to give input to the application.
Opens when users select a menu item or button.
\image qtcreator-dialog.png "Dialog"
\o Use the menu item or button name as the dialog name. You can
also combine the menu item or button name and the name of the
object that is managed in the dialog. For example, the \gui Add
button in the \gui Documentation options opens the
\gui {Add Documentation} dialog.
\row
\o Locator
\o Allows you to browse not only files, but any items defined by
locator filters.
\image qtcreator-locator.png "Locator"
\o You can add locator filters. Check that the filter is not
already in use and give the filter a descriptive name.
\row
\o Menu
\o Contains menu items that represent commands or options and that
are logically grouped and displayed. A menu can also contain
submenus.
\image qtcreator-menu.png "Menu"
\o You can create new menus. Use short, but descriptive names that
are consistent with existing menu names. Use unambigious names.
\row
\o Menu item
\o Represents a command or an option for users to choose.
\image qtcreator-menu-item.png "Menu item"
\o You can add new items to menus. Use short, but descriptive
names that are consistent with existing menu names. Use
unambigious names.
\row
\o Message box
\o Dialog that provides feedback to users, in the form of status
information, a warning, or an error message.
\image qtcreator-error-message.png "Message box"
Output from Qt Creator should be displayed in output panes,
instead.
\o Use the event as the title and provide a solution in the
message box.
\row
\o Mode
\o Modes correspond to complete screens of controls, specialized
for a task.
\image qtcreator-mode-selector.png "Mode selector"
\o You can add a mode for a new type of editor, for example.
Use descriptive, but short mode names. They have to fit in the
\gui {Mode selector}.
\row
\o Output pane
\o A pane displayed in the task pane that displays output from Qt
Creator.
\image qtcreator-output-pane.png "Output pane"
\o Use descriptive names for output panes.
\row
\o Sidebar
\o A view available in the \gui Edit and \gui Debug modes that
you can use to browse projects, files, and bookmarks, and to
view the class hierarchy.
\image qtcreator-sidebar-menu.png "Sidebar"
\o You can add views to the sidebar menu. Use descriptive names
for them.
\row
\o View
\o Available in \gui Debug mode, for interaction with the program
that is running under the control of the debugger.
\image qtcreator-debugger-views.png "Views"
\o ##Can you add views? How do \e views and \e panes actually
differ? Should we choose one of those terms and use it
everywhere?
\endtable
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment