Recipe 3.4. Checking the System Language

Problem

You want to know what language is used on the computer viewing the movie and how the user will input text.

Solution

Use the flash.system.Capabilities.language property and the flash.system.IME class.

Discussion

You can use the flash.system.Capabilities.language property to determine the language that is used on the computer on which the movie is being played. The property returns a two-letter ISO-639-1 language code (e.g., "fr" for French). Where applicable, a two-letter country code is appended, separated from the country code with a hyphen (e.g., "zh-CN" for Simplified Chinese and "zh-TW" for Traditional Chinese).

For a summary of language codes, see http://lcweb.loc.gov/standards/iso639-2/englangn.html and http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.

Here is an example of how to use the language property:

// Example output: en-US
trace(flash.system.Capabilities.language);

You can use this property to dynamically load content in the appropriate language:

// Create an associative array with language codes for the keys 
// and greetings for the values.
var greetings:Array = new Array(  );
greetings["en"] = "Hello";
greetings["es"] = "Hola";
greetings["fr"] = "Bonjour";

// Extract the first two characters from the language code.
var lang:String = flash.system.Capabilities.language.substr(0, 2);

// Use a default language if the language is not in the list
if (greetings[lang] == undefined) {
  lang = "en";
}

// Display the greeting in the appropriate language.
trace(greetings[lang]);

When you want to offer multiple language capabilities in your movies, you can choose from several different approaches. One, as shown in the preceding code, is to create associative arrays for all the text that appears in the movie. Another approach is to create static content in multiple movies (one for each language) and to load those movies based on the language code. With this technique, each .swf filename should include the language code, such as myMovie_en.swf, myMovie_es.swf, myMovie_fr.swf, etc.

// Get the language from the capabilities object.
var lang:String = System.capabilities.language.substr(0, 2);

// Create an array of the languages you are supporting (i.e., 
// the languages for which you have created movies).
var supportedLanguages:Array = ["en", "es", "fr"];

// Set a default language in case you don't support the user's 
// language.
var useLang:String = "en";

// Loop through the supported languages to find a match to the 
// user's language. If you find one, set useLang to that value 
// and then exit the for statement.
for (var i:int = 0; i < supportedLanguages.length; i++) {
  if (supportedLanguages[i] == lang) {
    useLang = lang;
    break;
  }
}

// Load the corresponding movie.
var movieURL:String =  "myMovie_" + useLang + ".swf");

It is also often important to know how a user will be entering text on her system. Languages, such as Chinese, Japanese, and Korean, can have thousands of possible characters. To enter these characters via the keyboard, a special program called an Input Method Editor (IME) is required. This is usually part of the operating system of the particular language.

To detect if the user's system has an IME, check the value of flash.system.Capabilities.hasIME, which will return true or false. Then use the flash.system.IME class to get more information about and interact with the IME. The flash.system.IME.enabled property tells you whether the user is using the IME or entering text straight from the keyboard. This property is actually writable, so you can use it to turn on the IME. On some platforms and OS versions, you can send a string to the IME to be converted into the correct characters, and accept the output of the IME back into a selected text field. Since this does not work on all systems, it is best to check the OS first (see Recipe 3.2).

See Also

Recipe 3.2