The recommended approach for localizing Parsley based applications is very different dependending on whether you are using Flex or not. For Flex Applications Parsley integrates with the Flex ResourceManager. For Flash Applications Parsley offers its own Localization Module. In fact that module is the only part that survived from version 1 of the framework, albeit with some major refactorings.
This is the only Parsley Localization feature that works the same way in Flex and Flash Applications, so we will explain it first.
You can place [ResourceBinding] metadata tags on properties of objects managed by the IOC Container:
[ResourceBinding(bundle="errorMessages",key="fileNotFound")]
public var message:String;
The tag has the following effects:
[Init] get invoked. In case the bundle is not yet available at the
time the object is initialized the resource may get injected at a later time. currentLocale
property of the Parsley ResourceManager gets changed (Flash Applications) the value for that property will be updated automatically. For Flex Applications it is recommended to use this feature primarily for objects defined in Parsley configuration classes or files (MXML or XML). For View Components, even when they connect to the Parsley IOC Container like described in 9 Dynamic View Wiring, you could just stick to normal Flex Binding syntax like this:
<s:Label text="{resourceManager.getString('RegistrationForm','city')}"/>
This way your localized View Component does not depend on the Parsley Framework at all. The Parsley [ResourceBinding] tag still may come in handy for other localized objects.
For Flash Applications the [ResourceBinding] tag is usually the recommended approach for localizing
components.
In most cases the Parsley Framework will automatically detect if it is used in a Flex or Flash Application depending
on how Parsley is initialized. So the adapter that connects the class that processes the [ResourceBinding] tags
to either the Flex or Parsley ResourceManager will be set automatically. There are a few exceptions described in the
following sections.
Like for most other Parsley metadata tags there are corresponding MXML and XML tags that could be used alternatively:
MXML Example
<Object type="{SlideShowController}">
<ResourceBinding property="message" bundle="errorMessages" key="fileNotFound"/>
</Object>
XML Example
<object type="com.bookstore.catalog.SlideShowController">
<resource-binding property="message" bundle="errorMessages" key="fileNotFound"/>
</object>
For Flex Applications the [ResourceBinding] tag described in the previous section
is currently the only integration feature that is available (and probably the only feature you'll need in a
Flex environment). Otherwise you should use the Flex Localization features the same way
like you would without using the framework. There is extensive documentation available in the
Flex Livedocs.
We might think about expanding the Flex Module Support to include management of dynamically loaded Flex Resource Modules which are associated with a particular Flex Module. But we will wait for feedback on this and see how the Module Support gets used.
Initializing the ResourceBinding metadata tag support for Flex
Whenever you are using the FlexContextBuilder to initialize your MXML-based
Parsley Configuration the framework will automatically set the required adapter for you.
In rare cases where you would build a Parsley Flex Application but not use MXML configuration at all (for example
confining yourself to use XML configuration files) you'd need to set the adapter manually:
ResourceBindingDecorator.adapterClass = FlexResourceBindingAdapter;
For Flash Applications Parsley offers its own Localization Module. This is the oldest part of the framework that already existed in early AS2 versions of the framework. But it's still a good solution if you are not using Flex. This section describes how you configure and use this module.
This functionality is not part of Parsley Core. The extension is available on the Parsley download page. Simply add the SWCs from the download to your classpath.
Parsley includes a separate XML configuration namespace that you can use to declare the bundles that the framework should load when initializing the IOC Container:
<objects xmlns="http://www.spicefactory.org/parsley"
xmlns:res="http://www.spicefactory.org/parsley/flash/resources"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.spicefactory.org/parsley
http://www.spicefactory.org/parsley/schema/2.3/parsley-core.xsd
http://www.spicefactory.org/parsley/flash/resources
http://www.spicefactory.org/parsley/schema/2.3/parsley-resources-flash.xsd">
<res:resource-manager id="resourceManager">
<res:locale language="en" country="US"/>
<res:locale language="de" country="DE"/>
<res:locale language="fr" country="FR"/>
</res:resource-manager>
<res:resource-bundle id="tooltips" basename="messages/tooltips" localized="true"/>
<res:resource-bundle id="alerts" basename="messages/alerts" localized="true"/>
<!-- other object definitions ... -->
</objects>
In the example above we declare a ResourceManager and the supported locales. In a modular application you should only declare a single ResourceManager instance (usually in the main application Context initialized on application start). You can then add any number of ResourceBundles in the main Context as well as child Context configurations. In the example above we add two bundles, one for tooltips and one for alerts.
With the basename attribute you specify how Parsley concatenates the actual names of the files it attempts to load.
For the basename messages/tooltips and the active locale en_US it would look for the following files:
This way you could keep messages that differ for each country in tooltips_en_US while adding messages
which are the same for each country with English messages to tooltips_en.xml. You can reduce the number of
files Parsley attempts to load though: When you set the ignore-country attribute to true the third file from
the list will be omitted, if you set the localized attribute to false the second one will be omitted, too.
Since this is an extension it has to be initialized explicitly before using the XmlContextBuilder:
FlashResourceXmlSupport.initialize();
The structure for the bundle files themselves is quite trivial:
<resource-bundle
xmlns="http://www.spicefactory.org/parsley/flash/resource-bundle"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.spicefactory.org/parsley/flash/resource-bundle
http://www.spicefactory.org/parsley/schema/2.3/parsley-resources-flash-bundle.xsd"
>
<resource key="tooltip.save">Saves the file</resource>
<resource key="tooltip.open">Opens a new file</resource>
<resource key="tooltip.saveAs">Saves the file with a new name</resource>
<resource key="tooltip.delete">Deletes the file</resource>
</resource-bundle>
If you want to switch the active locale at runtime (and thereby trigger updates for properties
marked with [ResourceBinding]), you can inject the configured ResourceManager into any
object and set its currentLocale property:
[Inject]
public var resourceManager:ResourceManager;
public function switchLocale (lang:String) : void {
resourceManager.currentLocale = new Locale(lang);
}
This will trigger the loading of the XML bundle files associated with that locale.
The ResourceManager will dispatch a LocaleSwitchEvent.COMPLETE event when the
loading process has completed. But in many cases you don't even have to listen for that
event as the ResourceBindings will update automatically. You only need this event
if switching the locale involves more than just updating property values.