Locale API

The Locale API allows MIDlets to retrieve locale information stored on the device. MIDlets can use the Locale API to:

Retrieve the currently used locale, that is, the default locale
Retrieve all supported locales
Retrieve the language and country codes of a locale
Compare two locales for equality
Receive a notification whenever the locale is changed

The locale used by a device is based on the currently selected UI language. The locale consists of a two-letter lower-case language code and optionally a two-letter upper-case country code, separated by a dash, for example "en-US" for "English (US)". For a full list of locales supported by the Series 40 and Symbian platforms, see section Supported locales.

Tip: You can also retrieve the currently used locale from the microedition.locale system property.

API contents

The Locale API consists of the following classes and interfaces (packaged as part of the Nokia UI API):

Locale
Use the Locale interface to retrieve the language and country codes of a locale or to compare two locales for equality. A Locale object represents a locale stored on the device.
LocaleListener
Use the LocaleListener interface to implement a listener for receiving a notification whenever the locale is changed.
LocaleManager
Use the LocaleManager class to retrieve the currently used locale, retrieve all supported locales, or register or remove a LocaleListener.

The Locale API also provides the com.nokia.mid.ui.locale.version system property, which MIDlets can use to query the Locale API version supported by the device.

The Locale API is supported since Nokia UI API 1.6.

Device compatibility

The Locale API is supported on Series 40 devices with Java Runtime 2.0.0 for Series 40 or newer.

Using the Locale API

The following code snippet shows how to retrieve the currently used locale.

// Get LocaleManager singleton instance
LocaleManager localeManager = LocaleManager.getInstance();

// Retrieve the currently used locale
Locale currentLocale = localeManager.getDefaultLocale();

The following code snippet shows how to retrieve the language and country codes of each locale supported by the device.

LocaleManager localeManager;
Locale[]      supportedLocales;
Locale        locale;
String        country;
String        language;

// Get LocaleManager singleton instance
localeManager = LocaleManager.getInstance();

// Retrieve all locales supported by the device
supportedLocales = localeManager.getAvailableLocales();

for(int i=0; i<supportedLocales.length; i++) {
    locale = supportedLocales[i];
    // Retrieve the language and country codes of the locale
    country = locale.getCountry();
    language = locale.getLanguage();
}

The following code snippet shows how to compare two locales for equality. The code snippet assumes that the Locale objects are already available.

// Returns true if locale1 and locale2 are equal
boolean equals = locale1.equals(locale2);

The following code snippet shows how to receive a notification whenever the locale is changed. The code snippet assumes that the containing class implements LocaleListener.

// Get LocaleManager singleton instance
LocaleManager localeManager = LocaleManager.getInstance();

// Register a LocaleListener (current class)
localeManager.addLocaleListener(this);

// Implement localeChanged required for a LocaleListener
public void localeChanged(Locale newLocale) {
    // Handle the locale change as necessary,
    // use the newLocale object to access information
    // about the new locale
}