| Next revision | Previous revision |
| style:strings [2008/11/04 10:15] – first cut; still more to do kelnos | style:strings [2010/10/02 17:26] (current) – external edit 127.0.0.1 |
|---|
| ====== Strings Style Guide ====== | ====== 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. | 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. |
| |
| - 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. | - 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. |
| - 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. | - 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. |
| - 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. | - 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. |
| |
| - 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). | - 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). |
| - When describing something to the user in more than a single sentence, capitalize (and punctuate) as you would if you were writing prose. | - When describing something to the user in more than a single sentence, capitalize (and punctuate) as you would if you were writing prose. |
| | |
| | ==== Punctuation ==== |
| | |
| | - In general, unless you're writing prose, single-sentence and single-phrase UI elements should not end with a period. |
| | - The exclamation mark ("!") should be avoided. If you must use them, never ever ever use more than one of these consecutively. |
| | - Question marks ("?") are fine when asking a question, but one is always enough. |
| | - 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. |
| |
| ==== Forms of Address ==== | ==== Forms of Address ==== |
| |
| 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. | 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. |
| | |
| | ==== Dialog Implementation Details ==== |
| | |
| | Unless there's a good reason not to, [[http://www.xfce.org/documentation/api/libxfcegui4/XfceTitledDialog.html|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. |
| |
| ==== Text Involved in Layout ==== | ==== Text Involved in Layout ==== |