org.j3d.util
Class I18nManager

java.lang.Object
  org.j3d.util.I18nManager

public class I18nManager
extends java.lang.Object

Manager of all internationalisation in the toolkit.

This class acts as a singleton manager for internationalisation within j3d.org Code and all applications built on it. It may be used for any string resource that may require internationalisation - not just text on buttons but also error messages, log messages etc.

External Application Usage

An application should initialise this manager as soon as possible after startup - ideally before anything else happens. The initialisation ensures that the right resources are loaded before people start making queries. The initialisation process should provide an application name as a reference point for internationalisation preferences that are stored to preserve settings between runs of the application. In no application name is provided, then the preferences are not stored and it will need to be reset each time the application runs. The reason for the application name is that this manager is shared in a toolkit with many different potential end applications making use of it. The application names allows us to create separate sets of settings on a per-application basis rather than relying on global settings for the user's computer.

The second direct customisation point is to provide a base name for the resource bundle to be loaded. If no name is provided, it will load the resource bundle named config.i18n.j3dorgResources from the classpath. This class follows the normal naming conventions that are defined in ResourceBundle. Any application providing their own resource bundle must provide values for every chefx3d resource that is specified in the base file that comes with this toolkit. Failure to do so will result in blank areas on the user interface and most probably an unusable application.

If an application wishes to also internationalise other settings, such as numerical representations, then you can query this class for the Locale it actually loaded, rather than the one you requested (fairly typical issue).

Note:

Because this class just stores string values, it is entirely possible to use it to store non-text information as well for a more generic internationalisation system. For example, storing the names of icon files could be a valid use of this class, allowing localisation for more than just text, but also graphical resources.

Resource Bundle Property Naming Conventions

With a property file containing all the internationalisation of a probably very large application, naming conventions are a necessity. Properties that are internal to any j3d.org-specific user interface element will start with the package name, class name (case included) and finally the resource property name after that.

Version:

$Revision: 1.1 $

Author:

Justin Couch

Method Summary

void	changeLocale(java.lang.String language, java.lang.String country, java.lang.String variant) Manually change the locale to the given country and language settings to overrided the current settings.
java.lang.String	getApplication() Get the currently set application string that langauge settings are being used for.
java.util.Locale	getFoundLocale() Get the loaded locale that was used for the resources file This can be used to create matching other internationalisation implementation details such as currency and number formatters.
static I18nManager	getManager() Get the global instance of the internationalisation manager for the given root class.
java.lang.String	getRequestedCountry() Get the country code that is currently set.
java.lang.String	getRequestedLanguage() Get the language code that is currently set.
java.lang.String	getRequestedLanguageVariant() Get the language variant setting that is currently set.
java.lang.String	getResourceName() Get the name of the resource file that is being loaded.
java.lang.String	getString(java.lang.String property) Get the localised string for the given property name.
void	setApplication(java.lang.String appName, java.lang.String resourceFile) Set the manager to use the given application's set of localisation settings.

Methods inherited from class java.lang.Object

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

Method Detail

getManager

public static I18nManager getManager()

Get the global instance of the internationalisation manager for the given root class.

setApplication

public void setApplication(java.lang.String appName,
                           java.lang.String resourceFile)

Set the manager to use the given application's set of localisation settings. This method should only be called once during the entire lifetime of the application - ideally at the very start before any other users of this class will have had a chance to read it. Setting this value ensures that the preferences are stored per end user application of this class, and is not generic to all installed applications on the end user's computer that makes use of this library All references to get strings after this call will then use this specific application's language settings without need for further qualification. Setting null removes the application and sets the defaults for all users of this library that don't explicitly set an application name.

Parameters:

appName - A name string describing the end user application

resourceFile - If not null, use this as the resource bundle base name to be fetched, rather than the default file name

getApplication

public java.lang.String getApplication()

Get the currently set application string that langauge settings are being used for. If none is currently set, return null.

Returns:

The current application name or null if not set

getResourceName

public java.lang.String getResourceName()

Get the name of the resource file that is being loaded. If none is set, it will return the default file name used by this library.

Returns:

The name of the base resource file used for text strings

changeLocale

public void changeLocale(java.lang.String language,
                         java.lang.String country,
                         java.lang.String variant)
                  throws java.lang.IllegalArgumentException

Manually change the locale to the given country and language settings to overrided the current settings. This will be stored in user preferences and used for any subsequent accesses to this manager, and any time after this that the application is started, if and only if an application name has been set. If no application name is set, this will persist for the lifetime of this application instance, but be lost on restart.

Setting the language value to null will reset the system back to the default platform setting. The other arguments may be null or specified. If null, the defaults for those are used from the local platform settings.

Language and country strings are required to be the 2 letter identifiers used in the ISO specifications. See the documentation of Locale for more information about valid codes. The method will check for appropriate length codes and issue an exception if they are not two characters.

Parameters:

language - The language identifier to load

country - The optional country code to load

variant - The optional language variant to load

Throws:

IllegalArgument - exception if the country or language codes are not correctly formated (length and case)

java.lang.IllegalArgumentException

See Also:

Locale, http://www.loc.gov/standards/iso639-2/englangn.html, http://www.davros.org/misc/iso3166.txt

getFoundLocale

public java.util.Locale getFoundLocale()

Get the loaded locale that was used for the resources file This can be used to create matching other internationalisation implementation details such as currency and number formatters.

Returns:

The locale corresponding to the loaded resource files

getRequestedLanguage

public java.lang.String getRequestedLanguage()

Get the language code that is currently set.

Returns:

The current language code or null if not set

getRequestedCountry

public java.lang.String getRequestedCountry()

Get the country code that is currently set.

Returns:

The current country code or null if not set

getRequestedLanguageVariant

public java.lang.String getRequestedLanguageVariant()

Get the language variant setting that is currently set.

Returns:

The current language variant code or null if not set

getString

public java.lang.String getString(java.lang.String property)

Get the localised string for the given property name.