org.tridas.io
Class I18n

java.lang.Object
  org.tridas.io.I18n

public class I18n
extends Object

Provide localization strings.

Java's ResourceBundles are intended to do this, but they don't provide the level of support that most other libraries do.

For example, suppose you have a "Copy" menuitem.

 JMenuItem copy = new JMenuItem("Copy");
 

Of course, you should internationalize this. But you want to change the text, the mnemonic, and the keyboard accelerator. If you only had ResourceBundle to work with, you might end up with 3 lines of translation for every word in your program. Plus, you'd have to know the name of the I18n file you used, each time you wanted to use it. Most other libraries (like Powerplant on Mac and Win95 resources) let you put them all in one line, which makes the translator's job much easier. That's what this class does.

Now, all you have to say is:

 copy = &Copy [accel C]
 

There are several things going on here:

• "copy" is the key. When you want to refer to this entry, you'll ask for it by this name. The user never sees this.
• "Copy" (without the &) is the text of this key. This is what users will see in menuitems, buttons, and so forth.
• "C" (the thing right after the &) is the mnemonic. On most platforms (all except Mac), this letter is underlined, and users can jump to it by pressing this letter, or Alt and this letter (depending on platform and context).
• "accel C" is the keystroke. The user can press this at any time to invoke this command. You can use the modifiers "shift", "control", "alt", and "meta", or the special modifier "accel". "accel" is automatically turned into "control" on PCs (Windows and Linux), and "meta" (Java's term for "command") on Macs. You should normally use the generic "accel" modifier. You can also combine modifiers, like "shift accel S" (the standard keystroke for "Save As..."). The class javax.swing.KeyStroke takes these strings as input: you can say

   KeyStroke.getKeyStroke(I18n.getKeyStroke("copy"))
   

  to get a Swing KeyStroke object.

This is convenient, but it gets even better: normally, you don't even have to mess with keystrokes and mnemonics. You can simply use the Builder factory to do the dirty work for you:

 JMenuItem copy = Builder.makeMenuItem("copy");
 

Of course, if you just want the text (for making a printout, for example), you should still use I18n.getText().

Not all keys must have a keystroke, or a mnemonic. Note that those methods can return nulls.

These methods get their values from the resource bundle called "TextBundle". That is, the file is called "TextBundle.properties", or some variant, like "TextBundle_de_DE.properties".

Left to do

• The way getMnemonic() is set up, "Save &as..." will still show it as "S&ave as...". Bad, but not fatal.
• Add way to escape [/]/& in text; also, add markers so "this text is mnemonic/text/keystroke" and "this text is just a string" are separate(?)
• in getKeyStroke(), why not use Toolkit.getDefaultToolkit().getMenuShortcutKeyMask() instead of (?:) for command/control choice?

Version:

$Id: I18n.java 2285 2010-02-11 16:35:25Z aps03pwb $

Author:

Ken Harris <kbh7 at cornell dot edu>

See Also:

ResourceBundle

Method Summary

static KeyStroke	getKeyStroke(String key) Get the keystroke string for this key.
static Integer	getMnemonic(String key) Get the mnemonic character this key.
static Integer	getMnemonicPosition(String key) Get the position of the mnemonic character in the string Used for setDisplayedMnemonicIndex
static String	getText(String key) Get the text for this key.
static String	getText(String key, ArrayList<String> replace) Look up translation key, and return with each {0} style placeholder replaced with item in array
static String	getText(String argKey, String... argReplacing) Created by Daniel, easier way of using an arbitrary number of replacing strings.
static String	getText(String key, String replace) Look up translation key, and replace {0} with the second parameter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getText

public static String getText(String key)

Get the text for this key. The text has no special control characters in it, and can be presented to the user.

For example, if the localization file has the line copy = &Copy [accel C], the string "Copy" is returned.

Parameters:

key - the key to look up in the localization file

Returns:

the text

getText

public static String getText(String key,
                             ArrayList<String> replace)

Look up translation key, and return with each {0} style placeholder replaced with item in array

Parameters:

key -

replace -

Returns:

getText

public static String getText(String argKey,
                             String... argReplacing)

Created by Daniel, easier way of using an arbitrary number of replacing strings.

Parameters:

argKey -

argReplacing -

Returns:

getText

public static String getText(String key,
                             String replace)

Look up translation key, and replace {0} with the second parameter

Parameters:

key -

replace -

Returns:

getKeyStroke

public static KeyStroke getKeyStroke(String key)

Get the keystroke string for this key. This string can be passed directly to the Keystroke.getKeyStroke() method.

For example, if the localization file has the line copy = &Copy [accel C], the string "control C" is returned (or on the Mac, "meta C").

If the string has no [keystroke] listed, null is returned.

Parameters:

key - the key to look up in the localization file

Returns:

the keystroke

getMnemonic

public static Integer getMnemonic(String key)

Get the mnemonic character this key.

For example, if the localization file has the line copy = &Copy [accel C], the character "C" is returned.

If the string has no &mnemonic listed, null is returned.

Parameters:

key - the key to look up in the localization file

Returns:

the integer representing the mnemonic character

getMnemonicPosition

public static Integer getMnemonicPosition(String key)

Get the position of the mnemonic character in the string Used for setDisplayedMnemonicIndex

Parameters:

key -

Returns:

an Integer, or null