I18NMnemonics

Revision as of 12:08, 5 November 2009 by Admin (Talk | contribs)


Mnemonics I18N Guildelines for netbeans based products to enable efficient localization


Contact kfrank@netbeans.org for more information or with comments or questions about these pages.



Overview:

NOTE - in the examples below, when you see an ampersand with quotes around it, ie FILE='&'File

ignore the quotes; they are put in to avoid the '&' itself from being not shown in the wiki interpretation of what the '&' means



How to Define Mnemonics in a Property File


Official Policy for NetBeans:

The '&' method (single bundle entry with ampersand-prefixed mnemonic) is the preferred and recommended way of setting mnemonics. ( as opposed to the "2 key/value" approach)

The other approach (2 key/value pairs) is considered obsolete and should be avoided.

It's true that both styles can still be found in the existing NB codebase and it's being fixed ongoing. but the only way that should be used is the '&' approach

See the Mnemonics class in the NetBeans API javadoc.



Guidelines:

Make key names and values of mnemonic descriptions and letters unique in a given Bundle.properties file. There should NOT be duplicate key names in any Bundle file.

   * Always use "&" to denote the mnemonic letter. The "&" should be placed in front of the designated mnemonic letter. Never rely on the default behaviour which is that if there is no "&" used, the first lettter of the word will be the mnemonic key.

# If no '&' is specified, then the first character of the value is used by default. But for a message that would be localized, the mnemonic then would be a non alphanumeric character, which is not allowed and thus the mnemonic would not work, so please always use the '&' for these type of mnemonics to explicitly assign a letter to be the mnemonic, even if it is the first charcter of the label.

For example, if there is a menu item with its label defined in the bundle file as:

THIS_MENU=This Menu

the menmonic would be "T" since no '&' is specified, that is, the first character of "This Menu"

But when translated, the first character is a multibyte charcter, which is not found on the keyboard, so the mnemonic does not work.

Solution is to always use the '&' before the character desired to be the mnemonic, even if the first character.

Then, when translated, localization can add the '&' to their translation as:

THIS_MENU=ZZZZZ'&'T "where ZZZZZ is the multibyte, but the T is the English character of the desired mnemonic letter. Its ok for the localization that this English letter show at the end of the line and in fact, it indicates to the user what the mnemoic is, in addition to the underlined T.

Examples:

Add_button= '&'Add

Delete_button= '&'Delete

Display_button=Dis'&'play


* When defining a label, it is preferred that there is a way to identify if the label is for title, message, button, etc.

Examples:

# File Error Dialog: FED

FED_title=File Error

FED_msg=File Error occurs.

FED_OK_button='&'OK

# End of File Error Dialog


2. How to Place Mnemonics in Property Files

Rules:

    * Group all mnemonics (whether it is method 1 or method 2) at the top of a property file.
   * If possible, place all label and mnemonic assignments from the same window/pop-up/dialog/etc. in the same file.
   * Place a comment at the top of the file, specifying to which window/pop-up/dialog/etc. they belong to.
   * It is preferred to have one-to-one mapping of winodow/pop-up/dialog/etc. to one property file. If label and mnemonic assignments from multiple window/pop-up/dialog/etc. are defined in a single property file, clearly separate them in the file and denote the window/pop-up/dialog/etc. name at the top of each section.



Example 1: One property file for one window

Top of the file...

=========================================

Name: name/id of the window that uniquely identifies this window

Description: description of this window
=========================================

File='&'File

Open='&'Open ..

Example 2: One property file for multiple windows/pop-up's/dialogs.

Top of the file...

=========================================
#Name: name/id of the window that uniquely identifies this window
#Name: name/id of the pop-up that uniquely identifies this pop-up
#Name: name/id of the dialog that uniquely identifies this dialog
#=====================================================
# Name: name/id of the window that uniquely identifies this window
# Description: description of this window
=========================================

File='&'File

Open='&'Open ..

=========================================
# Name: name/id of the pop-up that uniquely identifies this pop-up
#Description: description of this pop-up
=========================================

Close_button='&'Close

..

=========================================
# Name: name/id of the dialog that uniquely identifies this dialog
# Description: description of this dialog
#=====================================================

Confirm_msg=C'&'onfirm

..



3. How to Choose a Letter to Assign for the Mnemonic key


Rules:

   * If possible, keep the same mnemonic letter for same labels. For example, for label "Project Folder", the mnemonic should be "d" (or whatever we agree on); it is preferred to be consistent throughout the project as much as possible. In case if it cannot be accomplished due to conflicts, exceptions are accepted.
   * When there are multiple letters to choose from, try avoiding unsuitable letters such as "i", "j", "g", "l", "q", and "y". The mnemonics can be easily missed by "i", "j", and "l", because these letters are too slim. The mnemonics can also be easily missed by "j", "g", "q", and "y", because of the pixels under the base line.
   * Always review properties files for duplicates that cause conflicts.
   * Keep in mind that mnemonic letters are not case sensitive.
   * Always use ASCII characters for mnemonics. Mnemonics will always be ASCII characters, even for countries that use multi-byte characters.
   * European locales set the mnemonics based on their translated strings; hence they have different rules from English mnemonic assignments. This is taken care of by the localization team.

Guidelines:

   * Use common mnemonics as they appear in Table 1 below.
   * If the mnemonic does not appear in the table of common mnemonics (Table 1), choose the first letter of the menu item. (For instance, choose J for Justify.)
   * If the first letter of the menu item conflicts with those of other items, choose a prominent consonant. (For instance, the letter S may have already been designated as the mnemonic for the Style command. Therefore, choose the letter Z as the mnemonic for the Size command.)
   * If the first letter of the menu item and the prominent consonant conflict with those of other menu items, choose a prominent vowel.
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo