Localizing your application and using resource bundles

The BlackBerry Tablet OS SDK provides support for localization. You can use the classes in the qnx.locale package to localize your application, load locale-specific images, or load a resource bundle to provide flexibility to a control. The BlackBerry PlayBook tablet sets and maintains a locale value at runtime. The locale value represents the language of the current user. You can create a resource bundle for each locale that contains a set of key-value pairs for each locale-specific string in your application.

Your application can listen for locale changes, then load locale-specific resources to reflect the user's current locale. You can also include graphic assets in the locale folder for your application to load specific images for a given locale.

Resource bundles are loaded asynchronously and your application can load a resource string after a resource bundle has finished loading. The Event.CHANGE event is dispatched only after the resource bundles have loaded, thus decreasing the likelihood that your application will reference a missing resource.

In addition to providing locale support, you can use a resource bundle to change the context of a given control, regardless of the locale of the device or application. For example, the keyboard uses resource bundles to load a unique set of key characters depending on the context of the keyboard.

The following table provides a brief description of the qnx.locale package.

Class Description

Locale

You can use the Locale class to represent the locale of the device.

LocaleManager

You can use the LocaleManager class to interact with the device locale, set the locale of your application, listen for locale change events, and set and return the path to the locale-specific resource bundle.

LocaleResourceBundle

The LocaleResourceBundle class represents the files that contain the resource strings that you can create to provide locale-specific text for your application.

Localize an application

  1. Import the required classes and interfaces.
    import flash.display.Sprite;
    import flash.events.Event;
    
    import qnx.locale.LocaleManager;
    import qnx.ui.data.DataProvider;
    import qnx.fuse.ui.listClasses.List;
    import qnx.fuse.ui.listClasses.ListSelectionMode;
    import qnx.fuse.ui.text.Label;
  2. Add the following statement to your class before the class declaration. This statement sets the width, height, frame rate, and background color of the Stage.
    [SWF(width="1024", height="600", backgroundColor="#cccccc", frameRate="30")]
  3. Create an application framework by extending the Sprite class.
    public class MyLocaleChangeSample extends Sprite
    {
  4. Create instance variables to store a List object, a Label object, and a data provider.
        private var myList:List;
        private var myLabel:Label;
        private var myDP:DataProvider;
  5. Create a constructor for your class and invoke the initializeUI() method. Also, initialize your data provider.
        public function MyLocaleChangeSample()
        {
            initializeUI();
            myDP = new DataProvier();
        }
  6. Create initializeUI() and create an instance of the LocaleManager object. In the following code sample, an event listener is added to listen for locale change events.
        private function initializeUI():void
        {
    
            //Listen for locale changes.
            var lm:LocaleManager = LocaleManager.localeManager;
            lm.addEventListener(Event.CHANGE, onLocaleChange);
  7. Create a label and a list. The Label and List instances will reference Strings in the resource bundle.
            myLabel = new Label();
            myLabel.setPosition(100, 150);	
            stage.addChild(myLabel);
    
            myList = new List();
            myList.setPosition(100, 200);			
            myList.width = 400;
            myList.height = 500;			
            myList.selectionMode = ListSelectionMode.MULTIPLE;
            stage.addChild(myList);
            }
  8. Create the onLocaleChange() method. The event listener calls onLocaleChange() function when the device locale changes.
        private function onLocaleChange(event:Event):void
        {
  9. Add items to your data provider and set the text property of the LabelButton. In this step, the getResource() method is called to return the string that is associated with the specified resource key. The localeManager class returns the resources that are defined for the current locale. This code sample assumes that the resource bundles are present at runtime.
            myDP.setItems([{label: LocaleManager.localeManager.getResource("list-tomato")},
                           {label: LocaleManager.localeManager.getResource("list-potato")},
                           {label: LocaleManager.localeManager.getResource("list-asparagus")},
                           {label: LocaleManager.localeManager.getResource("list-bacon")},
                           {label: LocaleManager.localeManager.getResource("list-celery")},
                           {label: LocaleManager.localeManager.getResource("list-corn")}]);
    
            myLabel.text = LocaleManager.localeManager.getResource("label-title");
  10. Set the dataProvider property of your list to the DataProvider object you populated in step 9.
            myList.dataProvider = myDP;
        }
      }
    }