Strings Style Guide

Note: This document is of course not yet complete. In the interest of openness, I'll refrain from locking this page, but I ask that you limit your edits to fixes of typos and trivial errors.

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.

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 in a comment in the source line right above the string. These comments should get extracted automatically and put in the .pot file for the translator to see.
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.

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.

1. In general, unless you're writing prose, single-sentence and single-phrase UI elements should not end with a period.
2. The exclamation mark (“!”) should be avoided. If you must use them, never ever ever use more than one of these consecutively.
3. Question marks (“?”) are fine when asking a question, but one is always enough.
4. Punctuation does not get leading spaces in American English. So “Icon size:” and “Delete file foo?” are both correct, but “Icon size :” and “Delete file foo ?” are incorrect.

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.”

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 ^_~ .)

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.

Unless there's a good reason not to, XfceTitledDialog should be used for settings dialogs. The “subtitle” string for the dialog should be used as a description of what the dialog does or of what the user can use the dialog for, and should not be used to ask the user to do something.

For example, in a (fictitious) settings dialog that allows the user to configure various text layout parameters, the title might be simply “Layout” or “Layout Settings,” and a good subtitle might be “Configure text layout parameters,” “Text layout configuration,” or, if you're feeling a bit more verbose, even possibly “Control various parameters related to text layout” (though I'd recommend something shorter).

Transient dialogs that are opened to ask the user a question or to allow the user to input some data before being dismissed generally shouldn't use XfceTitledDialog.

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

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.

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.

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.