qtcreator-ui-text.qdoc 14.8 KB
Newer Older
1 2
/****************************************************************************
**
3
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
hjk's avatar
hjk committed
4
** Contact: http://www.qt-project.org/legal
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
**
**
** 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.
**
**
****************************************************************************/

/*!
    \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
55 56
    content words and phrases. However, it is more important that the text is
    useful and easy to understand.
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78

    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

79 80
        \o  Use full stops in messages.

81 82
        \o  Never user full stops (.) at the end of menu item names.

83 84
        \o  Place three full stops (...) at the end of menu item names that
            open a dialog requiring user action.
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104

        \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
105
    case, use book style capitalization and do not add a period after the tool
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
    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

134 135
    Check that messages are concise and economically formulated. However, it
    is more important that the messages are useful and easy to understand.
136 137 138 139 140 141 142

    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

143
        \o  Cannot send log as selected message type. Text is too long.
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

        \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

    Two styles are used, book title and sentence style:

    \list

        \o  Example of Book Title Capitalization

        \o  Example of sentence style capitalization

    \endlist

167 168
    \section2 Using Book Style Capitalization

169 170 171 172
    When using book style capitalization, capitalize all words, except
    prepositions that are shorter than five letters (for example, 'with' but
    'Without'), conjunctions (for example, and, or, but), and articles (a, an,
    the).
173
    However, always capitalize the first and last word.
174

175 176 177 178 179 180 181 182 183 184 185 186 187 188
    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

189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
    \section3 Checking Book Style Capitalization

    You can use the to-title-case.js script in the \c{\doc\titlecase}
    folder to check book style capitalization of UI text or headings in
    documentation:

    \list 1

        \o  Open to-title-case.html in a browser.

        \o  Enter the UI text in the field.

        \o  Click \gui Convert.

    \endlist

    The UI text with suggested book style capitalization is displayed in the
    field to the right.

    \note The script is based on word lists; it does not perform grammatical
    analysis. Therefore, it might get the capitalization wrong if you use a rare
    meaning of a word. For example, should you mean feathers and not direction
    when you write \e down. However, you should be able to trust it in most
    cases in the context of writing UI text and technical documentation.

    \section2 Using Sentence Style Capitalization

216 217 218
    When using sentence style capitalization, capitalize only the first letter,
    except proper names.

219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
    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
273
                and "%1" formatting instead. For example, use:
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402

                \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
403 404 405
            \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
406 407
                that is running under the control of the debugger.
                \image qtcreator-debugger-views.png "Views"
408
            \o  Use descriptive names for views.
409 410 411
    \endtable

*/