forked from qt-creator/qt-creator
378 lines
14 KiB
Plaintext
378 lines
14 KiB
Plaintext
/****************************************************************************
|
||
**
|
||
** 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. However, it is more important that the text is
|
||
useful and easy to understand.
|
||
|
||
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. However, it
|
||
is more important that the messages are useful and easy to understand.
|
||
|
||
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 is 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 <20>%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")}
|
||
\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 An area of the screen that displays information for users and
|
||
provides them with functions for managing the information.
|
||
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 Use descriptive names for views.
|
||
\endtable
|
||
|
||
*/
|