Xfce Wiki

Sub domains
 

This is an old revision of the document!


Strings Style Guide

Xfce has a bunch of text in its user interface (imagine that!), spread out among settings dialogs and the actual app interfaces. Ideally, the style of these strings should be consistent. Style can include word choice, sentence structure, grammar, etc. I'll attempt to collect some common style choices here. Obviously, documenting things like word choice is difficult, so I'll stick to the more abstract stuff.

Being Translator-Friendly

This stuff doesn't belong in a style guide, necessarily, but you should be thinking about the following anyway, so I'll put it here.

  1. Avoid using g_strconcat() or g_strlcpy()/g_strlcat() to construct contiguous blocks of UI text from smaller strings. This makes things difficult for translators. Use g_strdup_printf() or g_snprintf() with a format string. Just because the string fragments are in one order in English, it doesn't mean they'll be in the same order in other languages. Using a format string allows translators to rearrange the order of words in the final string.
  2. If seeing a short string of text out of context might be confusing for a translator, include a short context description at the start of the string, and separate it from the “real” string with the pipe character (“|”). Gettext will strip off the context for you when displaying the string in the user interface.
  3. Don't use colloquial language where possible. Many non-native English speakers (including the translators) may not understand your English-language in-joke, and will either translate it incorrectly, or have to waste time asking you what you meant.

General English Usage

Capitalization

  1. When in doubt, capitalize the first letter of the first word in a string of text.
  2. Capitalize the first letter of each word in window titles (using standard English title capitalization rules; e.g. “a,” “of,” “the,” etc. are not capitalized unless they are the first word).
  3. When describing something to the user in more than a single sentence, capitalize (and punctuate) as you would if you were writing prose.

Forms of Address

  1. Avoid “giving the computer a persona” by using first person pronouns. As much as high school English teachers may warn of the evils of passive voice, that's probably what you should be using. “I can't open files of type foo” is better stated as “Files of type foo are not supported.” “I lost your file in a freak deletion accident” should be “Your file was lost in a freak deletion accident.”
  2. Most of the time, avoid addressing the user directly. A dialog that says, “You have unsaved changes. Do you wish to save before exiting?” can just as easily be written, “There are unsaved changes. Save before exiting?” While the last bit (“Save before exiting?”) might not be considered the best choice grammatically, it has the virtue of being shorter, more to the point, and less demanding of the user.
  3. In contradiction to what I'll likely later say about using impeccable grammar… drop pronouns when possible (this is easier in other languages where pronouns are often optional, but English usually requires them). Part of the reason is that using pronouns often would violate rule #1 above: “I am unable to connect to the remote computer.” It's better to shorten that to “Unable to connect to the remote computer.”

Random Stuff

  1. Shorter is better, especially for popup message dialogs. The less the user has to read and internalize to understand what's going on, the happier they will be. Having said that, don't sacrifice understanding for brevity.
  2. Avoid the word “utilize.” “Use” is almost always the correct choice.
  3. Don't over-use dashes between words. (I'm looking at you, Germans ^_~ .)

Settings Dialogs

Generally, settings dialogs consist of lots of short strings of text describing an option, often (well, hopefully often) with a tooltip that explains in a bit more detail.

Text Involved in Layout

The text included in the header of a UI frame should be capitalized like a title (see “Capitalization” above).

Checkboxes and Radio Buttons

  1. Generally, don't use the word “enable” as the first word of a checkbox's text. Duh, it's a UI control with on and off states: of course it enables/disables. Use a simpler word, like “use,” e.g., “Use mouse emulation” or “Show desktop menu.”
  2. Avoid “sense-reversing”: an option to “Disable network access” with a checkbox is slightly counter-intuitive. Enabling the checkbox disables network access, really? Make the checkbox enable the option when the checkbox is enabled, and set the default appropriately.
  3. Capitalize the first word, and none of the others (unless there's a proper noun in the text). Do not end the text with a period. If you actually have several full sentences as part of a checkbox's text, you're probably doing something wrong.

Labels Before Controls

  1. Like other text, the first word should be capitalized, while the rest are not.
  2. When the label is before a control, such as descriptive text to the left of a dropdown box, append a colon to the string, with NO SPACE between the last letter of the string and the colon.

Tooltips

  1. Tooltip text should be limited to a single sentence, if possible, and the sentence should NOT be terminated with a period. Really try to cut it down if you can, using tricks such as a comma and conjunction, or a semicolon (assuming doing so isn't grammatically retarded). If you must use more than one sentence, use normal punctuation with terminal periods.
  2. If you can't think of anything more to say about an option and are considering making the tooltip say roughly the exact same thing as the control it's attached to, don't. Just don't add a tooltip.