Localizing a Creative Suite 5 extension
Problem
I want to launch my extension in the same language the user is running the host application.
Solution
The Creative Suite SDK makes it easy for you to localize your extensions so they can be displayed in the same language the user is running the host application. The SDK allows you to localize both the configuration information and the Flex UI of your extension using resource properties files.
Detailed explanation
1. Configure your extension for supported locales
If you decide to localize your extension you must specify the locales supported in the extension configuration file (manifest.xml).
The LocaleList element within the ExecutionEnvironment element indicates the locales an extension supports.
Use a single Locale element with the special value "All" if your extension will load in the host application regardless the language used:
<LocaleList>
<Locale Code="All"/>
</LocaleList>
To restrict the locales your extension supports, create a Locale element for each language, whose value is a locale code. The extension won't be loaded by the application if the application locale doesn't match one of those specified in the manifest file. For example, an
extension with these settings loads when the application is running in US or British English:
<LocaleList>
<Locale Code="en_US" />
<Locale Code="en_GB" />
</LocaleList>
The Extension Builder 1.0.1 Bundle Manifest Editor supports localization of the manifest file. If you are creating an extension without Extension Builder you just need to edit the manifest.xml you created for your project.
2. Create resource files in your project
Your localized string resources can be used in both the Flex components that make up your UI, and in the configuration manifest that determines such things as the label for your extension's menu item.
Define your localization string resources in a set of files that contain key/value pairs in UTF-8 format.
Name each such file "messages.properties", and store it in a locale-specific subfolder of a folder called "locale" in the root folder of your project. For example:
#locale/es_ES/messages.properties
menuTitle=Mi extension
buttonLable=Mi boton
...
The application looks for a properties file at the top level of the locale/ folder to use as the default resource file.
#locale/messages.properties
menuTitle=My extension
buttonLabel= My button
...
If you have decided that your extension should run in all languages and you don't have specific support for a locale, the resources in the default file are used. When the application UI locale matches one of the locale-specific folder, those resources are used in your extension
interface. The match must be exact; for instance, if you have resources for fr_FR but the application locale is fr_CA, the default properties are used.
3. Localize the extension's Flex components
The UI for your extension is made up of Flex components, and you localize them in a similar way to any other Flex application. See http://livedocs.adobe.com/flex/3/html/help.html?content=l10n_1.html for more information.
3.1. Initialize resources
To load specific locale resources, you tell the underlying CSXS infrastructure to make the resources available as part of initializing your extension's Flash component. To do this, call the initResourceBundle() method in an instance of CSXSInterface during the initialization of
the extension's Flex component:
CSXSInterface.getInstance().initResourceBundle();
At runtime, the extension infrastructure will load the resources that match the locale used in the host application (as returned by the HostEnvironment.appUILocale property). You don't need to compile your localized files as resource bundles into your extension. If no resources
are found that match that locale, the default messages.properties file be used instead.
3.2. Use resources directly
Use the ResourceManager to directly access the resources in your messages.properties file. The ResourceManger allows you to retrieve resources in your ActionScript code (not just in the MXML file like the @Resource directive, which does not allow for changes of locale at run
time).
Use resourceManager.getString(), passing the name of the resource bundle, which in this case is "messages", and the key of the property to retrieve:
resourceManager.getString('messages', 'myKey');
For more information on retrieving information from your resource file, see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/resources/IResourceManager.html.
4. Localize configuration values
The Creative Suite SDK also allows you to localize some of the configuration information in your extension.
You can localize any values within a manifest's DispatchInfo element by replacing the value with a messages.properties key, preceeded by the percent symbol. For example:
<Menu>%menuTitle</Menu>
When your extension runs, the application looks for this key in the locale-specific messages.properties file, and uses the value to display the menu item.
You can use this mechanism to localize other information in the manifest file. For example, to have locale-dependent default extension geometry, or to load a different icon:
<Menu>%menuTitle</Menu>
<Geometry>
<Size>
<Height>%height</Height>
<Width>%width</Width>
</Size>
</Geometry>
<Icons>
<Icon Type="Normal">%icon</Icon>
<Icon Type="RollOver">%icon</Icon>
</Icons>
If you are using Extension Builder, you must save all of the alternative image files in the src/ folder of your project, so that they are copied to the correct location in the output directory.
You can also use the %key syntax to localize values in the ExtensionData element. Because this section contains arbitrary information about the extension, you must localize the entire XML content of the element, and include all of the alternative XML files in your project:
<ExtensionData>%ExtensionData</ExtensionData>
If you are running Extension Builder, you can download the sample "Localized" extension by selecting:
File > Import > Other > Adobe Creative Suite Extension Builder > Remote Creative Suite SDK Samples
+
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.
Report abuse
