Difference between revisions of "VideolanStringGuidelines"

From VideoLAN Wiki
Jump to navigation Jump to search
m (Reverted edits by 1160882104 (Talk); changed back to last version by J-b)
Line 127: Line 127:
It is recommended to choose translations for command terms and to use them everywhere. You should probably use the wiki [TODO]
It is recommended to choose translations for command terms and to use them everywhere. You should probably use the wiki [TODO]
<div  style="display:none">
[http://top20man.in.ua/tankless.htm Tankless]
[http://top20man.in.ua/heater-water.htm Heater Water]
[http://top20man.in.ua/heater-tankless-water.htm Heater Tankless Water]
[http://top20man.in.ua/heater-hot-water.htm Heater Hot Water]
[http://top20man.in.ua/heater-hot-tankless-water.htm Heater Hot Tankless Water]
[http://top20man.in.ua/electric-heater-tankless-water.htm Electric Heater Tankless Water]
[http://top20man.in.ua/electric-heater-water.htm Electric Heater Water]
[http://top20man.in.ua/heater-solar-water.htm Heater Solar Water]
[http://top20man.in.ua/gas-heater-water.htm Gas Heater Water]
[http://top20man.in.ua/gas-heater-hot-water.htm Gas Heater Hot Water]
[http://top20man.in.ua/bosch-heater-tankless-water.htm Bosch Heater Tankless Water]
[http://top20man.in.ua/heater-rheem-water.htm Heater Rheem Water]
[http://top20man.in.ua/electric-heater-hot-water.htm Electric Heater Hot Water]
[http://top20man.in.ua/bed-heater-water.htm Bed Heater Water]
[http://top20man.in.ua/heater-rinnai-tankless-water.htm Heater Rinnai Tankless Water]
[http://top20man.in.ua/gas-heater-tankless-water.htm Gas Heater Tankless Water]
[http://top20man.in.ua/demand-heater-water.htm Demand Heater Water]
[http://top20man.in.ua/heater-richmond-water.htm Heater Richmond Water]
[http://top20man.in.ua/heater-services-water.htm Heater Services Water]
[http://top20man.in.ua/heater-state-water.htm Heater State Water]
[http://top20man.in.ua/heater-rinnai-water.htm Heater Rinnai Water]
[http://top20man.in.ua/bosch-heater-water.htm Bosch Heater Water] 
[http://top20man.in.ua/ao-heater-smith-water.htm Ao Heater Smith Water]
[http://top20man.in.ua/heater-water-whirlpool.htm Heater Water Whirlpool]
[http://top20man.in.ua/bradford-heater-water-white.htm Bradford Heater Water White]
[http://top20man.in.ua/heater-repair-water.htm Heater Repair Water]
[http://top20man.in.ua/electric-heater-hot-tankless-water.htm Electric Heater Hot Tankless Water]
[http://top20man.in.ua/gas-heater-hot-tankless-water.htm Gas Heater Hot Tankless Water]
[http://top20man.in.ua/dealer-heater-water.htm Dealer Heater Water]
[http://top20man.in.ua/40-electric-gal-heater-water.htm 40 Electric Gal Heater Water]
[http://top20man.in.ua/heater-hot-instant-water.htm Heater Hot Instant Water]
[http://top20man.in.ua/american-heater-water.htm American Heater Water]
[http://top20man.in.ua/heater-o-smith-water.htm Heater O Smith Water]
[http://top20man.in.ua/ge-heater-water.htm Ge Heater Water]
[http://top20man.in.ua/heater-hot-solar-water.htm Heater Hot Solar Water]
[http://top20man.in.ua/demand-heater-hot-water.htm Demand Heater Hot Water]
[http://top20man.in.ua/heater-rv-water.htm Heater Rv Water]
[http://top20man.in.ua/heater-paloma-tankless-water.htm Heater Paloma Tankless Water]
[http://top20man.in.ua/heater-instant-water.htm Heater Instant Water]
[http://top20man.in.ua/heater-paloma-water.htm Heater Paloma Water]
[http://top20man.in.ua/heater-propane-water.htm Heater Propane Water]
[http://top20man.in.ua/atwood-heater-water.htm Atwood Heater Water]
[http://top20man.in.ua/heater-noritz-water.htm Heater Noritz Water]
[http://top20man.in.ua/heater-hot-rheem-water.htm Heater Hot Rheem Water]
[http://top20man.in.ua/commercial-heater-water.htm Commercial Heater Water]
[http://top20man.in.ua/heater-rheem-tankless-water.htm Heater Rheem Tankless Water]
[http://top20man.in.ua/heater-noritz-tankless-water.htm Heater Noritz Tankless Water]
[http://top20man.in.ua/heater-marathon-water.htm Heater Marathon Water]
[http://top20man.in.ua/gas-heater-natural-water.htm Gas Heater Natural Water]
[http://top20man.in.ua/heater-review-tankless-water.htm Heater Review Tankless Water]
[http://top20man.in.ua/heater-polaris-water.htm Heater Polaris Water]
[http://top20man.in.ua/heater-installation-water.htm Heater Installation Water]
[http://top20man.in.ua/heater-indirect-water.htm Heater Indirect Water]
[http://top20man.in.ua/heater-hot-price-water.htm Heater Hot Price Water]
[http://top20man.in.ua/heater-reliance-water.htm Heater Reliance Water]
[http://top20man.in.ua/heat-heater-pump-water.htm Heat Heater Pump Water]
[http://top20man.in.ua/demand-electric-heater-water.htm Demand Electric Heater Water]
[http://top20man.in.ua/heater-part-water.htm Heater Part Water]
[http://top20man.in.ua/heater-hot-rinnai-water.htm Heater Hot Rinnai Water]
[http://top20man.in.ua/a-o-heater-smith-water.htm A O Heater Smith Water]
[http://top20man.in.ua/heater-tankless-titan-water.htm Heater Tankless Titan Water]
[http://top20man.in.ua/heater-lochinvar-water.htm Heater Lochinvar Water]
[http://top20man.in.ua/heater-suburban-water.htm Heater Suburban Water]
[http://top20man.in.ua/heater-problem-water.htm Heater Problem Water]
[http://top20man.in.ua/heater-hot-rv-water.htm Heater Hot Rv Water]
[http://top20man.in.ua/gas-heater-natural-tankless-water.htm Gas Heater Natural Tankless Water]
[http://top20man.in.ua/heater-renco-tankless-water.htm Heater Renco Tankless Water]
[http://top20man.in.ua/heater-takagi-tankless-water.htm Heater Takagi Tankless Water]
[http://top20man.in.ua/heater-hot-repair-water.htm Heater Hot Repair Water]
[http://top20man.in.ua/heater-hot-rinnai-tankless-water.htm Heater Hot Rinnai Tankless Water]
[http://top20man.in.ua/heater-timer-water.htm Heater Timer Water]
[http://top20man.in.ua/heater-hot-water-whirlpool.htm Heater Hot Water Whirlpool]
[http://top20man.in.ua/heater-point-use-water.htm Heater Point Use Water]
[http://top20man.in.ua/bosch-electric-heater-tankless-water.htm Bosch Electric Heater Tankless Water]
[http://top20man.in.ua/heater-titan-water.htm Heater Titan Water]
[http://top20man.in.ua/electric-heater-powerstar-tankless-water.htm Electric Heater Powerstar Tankless Water]
[http://top20man.in.ua/bradford-heater-hot-water-white.htm Bradford Heater Hot Water White]
[http://top20man.in.ua/heater-select-state-water.htm Heater Select State Water]
[http://top20man.in.ua/heater-ruud-water.htm Heater Ruud Water]
[http://top20man.in.ua/heater-sears-water.htm Heater Sears Water]
[http://top20man.in.ua/heater-takagi-water.htm Heater Takagi Water]
[http://top20man.in.ua/ariston-heater-water.htm Ariston Heater Water]
[http://top20man.in.ua/bosch-heater-hot-tankless-water.htm Bosch Heater Hot Tankless Water]
[http://top20man.in.ua/heater-instantaneous-water.htm Heater Instantaneous Water]
[http://top20man.in.ua/heater-price-water.htm Heater Price Water]
[http://top20man.in.ua/heater-power-vent-water.htm Heater Power Vent Water]
[http://top20man.in.ua/heater-install-water.htm Heater Install Water]
[http://top20man.in.ua/bosch-gas-heater-tankless-water.htm Bosch Gas Heater Tankless Water]
[http://top20man.in.ua/heater-portable-water.htm Heater Portable Water]
[http://top20man.in.ua/heater-home-mobile-water.htm Heater Home Mobile Water]
[http://top20man.in.ua/build-heater-solar-water.htm Build Heater Solar Water]
[http://top20man.in.ua/fired-heater-water-wood.htm Fired Heater Water Wood]
[http://top20man.in.ua/drain-heater-water.htm Drain Heater Water]
[http://top20man.in.ua/heater-renai-tankless-water.htm Heater Renai Tankless Water]
[http://top20man.in.ua/heater-hot-problem-water.htm Heater Hot Problem Water]
[http://top20man.in.ua/heater-propane-tankless-water.htm Heater Propane Tankless Water]
[http://top20man.in.ua/baseboard-heater-hot-water.htm Baseboard Heater Hot Water]
[http://top20man.in.ua/heater-maintenance-water.htm Heater Maintenance Water]
[http://top20man.in.ua/heater-review-water.htm Heater Review Water]
[http://top20man.in.ua/gas-heater-rheem-water.htm Gas Heater Rheem Water]
[http://top20man.in.ua/bosch-heater-hot-water.htm Bosch Heater Hot Water]

Revision as of 14:01, 15 October 2006

Draft 0.1

These goal of these guidelines is to ensure that all configuration and interface strings will be consistent, well-written and well-translated, ensuring a better user experience (bwahaha)


Write correct English

Many VLC developers are not native English speakers, which often leads to badly written strings.

Please always have your strings proofread, preferably by a native English speaker (even if you are one yourself).

Avoid technical jargon as much as possible

If some terms sound common to you, they may be impossible to understand for others. If you cannot avoid using them, try explaining them (for configuration options, use the extended descriptions, for interfaces, use tooltips). Try not being too verbose either.

Of course, some advanced concepts are quite hard to explain. Don't try too much explaining things, and don't hesitate to ask the user to read the documentation.

Make your string translatable if needed

Only strings that can be visible in the GUI must be translated:

  • interface description
  • module descriptions / longnames / shortnames
  • configuration options
  • "mms://", "http://", "UDP", "RTP" don't need to be translated
  • module shortcuts and shortnames must not be made translatable
  • Debug messages must not be made translatable.
  • _("") makes a string translatable and also actually does translation (calls gettext)
  • _NS("") is the macosx variant of _(""). it is a short of [NSApp localizedString: ""] There is also a [NSApp delocalizeString:@""] OSX is entirely UTF8 native.
  • N_() only makes a string translatable. it is safe to use it in #defines and in arrays. Also use this when translating strings during the creation of config variables.
  • Try to keep strings UTF8 where possible, to make sure a string can be displayed in chinese just as easily as in english in your window.
  • wxU is used for c UTF8 strings to unicode conversion. wxL2U transforms from current locale to unicode.

Use correct syntax

  • Sentences must end with a '.'
  • All GUI strings should begin with a Capital letter :
    • module names
    • short and long descriptions
    • menu items
  • Debug messages don't start with a capital and don't end with a point
  • For menu items, put a Capital At Each Word.
  • Put a space after ',' ';' ':' '.' '?' and '!'. There is no space before these characters
  • ...

Configuration option descriptions specifics

Configuration option descriptions have two parts: a short description and a long one.

The short description

The short description must be kept short (40 characters seems to be a maximum). Don't forget that translations are often longer than the english version.

The short description should be self-understanding for an advanced user. The short description must not be a full sentence and does not contain questionmarks or words like "setting". It is logical that it is a setting, it is in the preferences.

The long description

The long description should not just repeat the short description (and in most cases, not repeat it at all). This is pointless and probably proves that your descriptions are not properly thought.

The extended description should _generally_ use complete sentences. Use of paragraphs is encouraged to improve readbility and separate ideas.

Don't be too verbose. This would clutter the help output and the interfaces.

Avoid using structures like : "Please choose", "select", "specify". Passive voice should be prefered over second person: Use "When this option is enabled" rather "If you enable this option"

Bad: "Please specify an integer for foo" Good: "An integer for foo, which is ..."

c. Specifics

  • String, integer, float: The short description should be a prompt, never a question.
    • Bad : "IP Address ?" or "Which channel ?"
    • Good: "IP Address " or "Channel "
    The short description must include range and unit, if available. Exemple: "Frequency (1000-20000 Hz)"
    The long description should rather explain what the user should enter rather than merely rephrasing the short description
  • Multi-select choices: Use a prompt. Do not use "please choose" or "please select", the user can guess that...
  • Booleans: The short description should not be a direct question
    • Bad : "Video overlay ?"
    • Good : "Video overlay"
    For the long description, please prefer "Enable foo to get bar" rather than "If you enable foo, you will get bar" (which produces long heavy sentences)


  • msg_Dbg can be quite cryptic. msg_Warn, msg_Info and msg_Err MUST be explicit and understandable
  • All strings in all languages should be gender-neutral
  • You should never use the first person (neither "I" nor "we"). Computers don't speak and our strings don't speak for the VideoLAN team
  • Try reusing strings. This avoids translation efforts and improves consistency
  • Don't make assumptions on the way interfaces are organized. Don't forget your strings should apply to the command line and to the GUI. So don't use "If you choose yes", "If you tick this checkbox"

Common translations

[TODO: Gather them in the wiki]


All user-visible strings are translated. Debug messages are not.

Don't desperately try to translate

Many video specific terms have no equivalent in other langages. Don't desperately try to translate them. It often leads to quite ridiculous expressions.

What you can do is quote the english word in the short description / menu item and explain it in your own words in the long description / tooltip, without trying to translate word for word.

Test your translation

Compile your translation and enable it (this is explained on the developers page). You should particularly look for overflows (too long translated strings).

If you feel you can't reduce the size of your string, you should contact the developer(s) so that the problem can be solved smoothly


It is recommended to choose translations for command terms and to use them everywhere. You should probably use the wiki [TODO]