AS3-LocaleManager

The AS3-LocaleManager provides basic localization support for ActionScript apps. It takes care of loading/parsing resource bundle files (*.txt) and returns localized resources based on the precedence of the locales set in localeChain.

For some reason, mx.flex.ResourceManager does not always work as expected [1]. I ran into this issue while working on a AS3 project for AIR 3.6 (using Flash Builder 4.7). This class is a quick workaround for the problem.

[1] http://forums.adobe.com/message/5182578

Resource files

The bundle files are stored in app://locale/[locale]/[bundleName].txt (ie.: app://locale/en_US/localizedStrings.txt). Make sure the directory "locale" is copied to your build package:

• Put the directory locale in your src directory.
• Or add the directory containing 'locale' to your Source Path (Flash Builder: Project > Properties > ActionScript Build Path > Source Path).

The content format for bundle files is KEY = Value followed by a line break. You can use the "=" character within the value, but not for keys or comments.

# Any line without the "equals" character is a comment. 
A leading # does not harm.
LABEL_FIRSTNAME = Firstname
LABEL_LASTNAME  = Lastname

The locales are returned by precedence given in localeChain. Mix-ins are supported. This allows to work with incomplete bundles (ie. separate bundles for different regions of the same language).

Usage Sample

Resource files

// File: de_DE/bundleName.txt
// Complete resource file
CURRENCY_SHORT = EUR
PRICE          = Preis
USRMSG_UNLOCK  = Gratulation {0}, du hast jetzt {1}!

// File: de_CH/bundleName.txt
// Incomplete resource file (used as mix-in)
CURRENCY_SHORT = CHF

The sample uses mix-ins and placeholders.

Initialize LocaleManager and set localeChain

I recommend to use the handy LocaleUtil to sort supported locales based on system preferences.

var locales:LocaleManager = new LocaleManager();
locales.localeChain = LocaleUtil.sortLanguagesByPreference(
    ["de_CH", "de_DE", en_US], Capabilities.languages, "en_US");

Adding required bundles

Use addRequiredBundles to add all required bundles. This is typically used on startup. The bundle files are loaded/parsed at runtime. Adding only the required bundles saves time. You can safely omit useLinebreak:true if you do not use line breaks (\n) in your resource file (cmp. next example).

locales.addRequiredBundles([
    {locale:"de_DE", bundleName:"bundleName", useLinebreak:true},
    {locale:"de_CH", bundleName:"bundleName", useLinebreak:true}
], onComplete);

// optional complete responder
function onComplete(success:Boolean):void
{
    if ( success ) trace("Required bundles successfully added.");
    else trace("Adding required bundles failed.");
}

If you work with a single resource bundle per locale and you do not need mix-ins, this will do the job:

locales.addRequiredBundles([
    {locale:locales.localeChain[0], bundleName:"bundleName"}
], onComplete);

// complete responder (s. above)

Adding additional bundles

With addBundle you can add bundles later. If you have an app with many scenes/levels and many resources in your bundles it might be better to split the resources into several bundles and just load the ones really needed (ie. when switching levels).

locales.addBundle("en_US", "bundleName", false, onComplete);

// optional complete responder
function onComplete(locale:String, bundleName:String, success:Boolean):void
{
    if ( success ) trace("Bundle " + locale + "/" + bundleName + " added.");
    else trace("Adding bundle " + locale + "/" + bundleName + " failed.");
}

Use locales.localeChain[0] as parameter if you just need to add a single bundle for the primary locale.

locales.addBundle(locales.localeChain[0], "anotherBundleName", false, onComplete);

// complete responder (s. above)

Retrieving resources

getString returns a given resource of a given bundle. Localized of course. The third sample shows how to use placeholders and parameters.

// given localeChain ["de_CH","de_DE"]
locales.getString("bundleName", "PRICE"); // Preis
locales.getString("bundleName", "CURRENCY_SHORT"); // CHF
locales.getString("bundleName", "USRMSG_UNLOCK", ["Superman", "Superkraft"]); // Gratulation Superman, du hast jetzt Superkraft!

Make it better

Suggestions, improvements, feedback and whatever is welcome! @rekomat