Localization, Translation in Flash Builder 4

 

This article is meant to be a quick start guide to translating your flash application. I am going to explain how to get started with localization in Flash Builder 4 and Flash Builder 4.5. I am focusing on giving you an easy way to get your application multilingual as fast as possible. Localization in Flex 4 has a lot more to offer than is described in this article so I recommend that you also read the official Adobe documentation on localization to get the in depth information about localization. The Adobe article has quite a lot of text so I composed this quick start guide to get you started.

The first thing that we need to do is create the folders that will contain the translations. We start by creating a folder called locale in our project source folder. The default source folder in Flash Builder in called src. The folder locale is the one that will contain all our languages. We are going to use two languages, English and Swedish, and we therefore create two folders inside the locale folder and name them en_US and sv_SE. The name en_US means that the folder is for the English language for USA, and sv_SE means Swedish for Sweden. The reason that we use both the language and the country is that we might need different translations for the same language depending on which country the localization is for. For example en_GB would be an English translation for the Great Britain market.

The next thing that we need to do is to create a file named default.properties in the folder sv_SE. This is the file that will contain our translated strings. We give each string a label so that we can reference it later in the application.

# /locale/en_SE/default.properties 
test=Testar svensk text
test2=Vi testar igen

We also need to create the same file, default.properties, in the other folder, en_US. This file will contain the same labels as the Swedish file but with the English translated versions of the strings.

# /locale/en_US/default.properties 
test=This is the English test
test2=Another test

We only have one resource file per language in this example and have therefore chosen to name it default. It can be a good idea to split this file into smaller parts if you have a large application and name the files depending on what part of the application they are for.

The next step will be to open Properties for the project and then select Flex Compiler. In the text field Additional compiler arguments: you will need to add the following

-locale=en_US,sv_SE -source-path=locale/{locale} -allow-source-path-overlap=true

-locale specifies which locales to include in the compilation. -source-path specifies the location of the resources. -allow-source-path-overlap is optional, but if you do not set it then you might get a warning that the source path for the locale is a subdirectory of the projects source path.

We are going to use the ResourceManager to retrieve the localized text from the resource files. To do this we need to specify which resource package that we would like to use. The name of the resource package is the same as the file name that we chosen for the .properties file. Remember that we can have more than one resource file per language if we like. You specify which package to use with MXML like this

<fx:Metadata>
    [ResourceBundle("default")] 
</fx:Metadata>

If you want do the same thing for an ActionScript class the you do it like this.

[ResourceBundle("default")] 
public class MyClass extends UIComponent 
{   
}

We call getString to retrieve a localized text using the ResourceManager

resourceManager.getString('default', 'test');

default is the name of the package and test is the label for the string that we want to use.

To change the language we call

resourceManager.localeChain = ['sv_SE'];

This will change the selected language to Swedish for Sweden.

You can pass along variables as flashVars when you start the application to select which language to use as a default for the localization. The variable is called localeChain and should be set to the wanted language_country code.

<param name='flashVars' value='localeChain=en_US'/>

or if you are using SWFObject 2 in the default HTML template for Flex 4

flashvars.localeChain="en_US"

Now we are ready to test the localization. Run the code bellow and click on the button to change the language from English to Swedish.

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx" >
	
   <s:layout>
      <s:VerticalLayout />
   </s:layout>
	
   <fx:Metadata>
      [ResourceBundle("default")]
   </fx:Metadata>
	
   <mx:Text text="{resourceManager.getString('default', 'test')}" />
	
   <s:Button click="{resourceManager.localeChain = ['sv_SE']}" />
	
</s:Application>

This is all you need to know to get started and localize your flex application in Flash Builder 4.5. To learn more ready part 2 of my tutorial on localization here. You can find an example on localization in this game. Learn more about ActionScript, Flash Builder 4.5 and the Flex framework in our other tutorials on this site. I hope you found this AS3 guide to be helpful.