Translating the Control Panel

=Summary=

Control Panels beginning with version 2.8 are designed to be translated. Virtually all text items have been made dynamic, and the translations are driven by an external file rather than embedded in the FLA - this allows a single SWF file to handle multiple languages.

=translation.xml= This file provides the basic configuration of the translation, and is of the form:



The 'languageFile' attribute is a path to a file on the local filesystem that contains the actual translations. The file must use UTF-8 encoding and be well-formed XML.

Optional attributes:
 * testMode='true' auto-translates all translatable text to Pig Latin - useful for determining which text fields can be translated
 * debugMode='true' - outputs an XML fragment in the trace log for text that has not been found in the language file.
 * fontName='name of font' - used to substitute a font for the fonts used in the Control Panel (mainly Trebuchet MS).
 * fontWeight='bold' - used to use the bold variant of the specified font
 * fontHeightAdjust='100' - a percentage multiplier to apply to each text field's height to adjust to font metrics

The search path for this file is,  , then.

=languageFile.xml=

The file can appear wherever the translation.xml file specifies - it's of the form:

 ...

Where the attributes are:
 * o - the original (typically English) version of the text
 * t - the translated text to be substituted for the original

The file must use UTF-8 encoding and be well-formed XML. Pay particular attention to properly escaping XML entities.

=Font substitution=

The Control Panel, by default, uses 'Trebuchet MS' in most contexts, however, there are a few text fields using other fonts, typically Agenda or Arial. The translation mechanism incude the ability to substitute a single font for the default - this is typically used only for logographic fonts such as Japanese, Korean hanja, or Chinese, or non-Western phonemic fonts such as Korean hangul. In addition to the translation.xml file, you must also supply the desired font as a Flash 7 SWF, and a modified /psp/flashplayer.cfg to specify the font.

fonts.swf
Steps to create a fonts.swf file
 * Create a new Flash movie
 * Set the publish settings to output Flash 7
 * Add a dynamic text field to the stage
 * In the text field's properties panel, Select the font
 * Also in the properties panel, hit the "Embed..." button
 * Select the entry for "Basic Latin", and any additional glyphs that your font requires
 * Publish the SWF

You can add multiple fonts to the file as space permits - these fonts will be available under their names as device fonts for any widgets on the device.

/psp/flashplayer.cfg
In order to let the Flash Player know about these fonts, you need to create or edit the /psp/flashplayer.cfg file in UTF-8, adding the following entry:

CustomFontMovie /path/to/fonts.swf

In addition, one can add a line to map the device font aliases '_sans', '_serif' and '_typewriter' to fonts in the file, using the line:

CustomFontMap name_of_sans,name_of_serif,name_of_typewriter

Note that these are the names of the fonts as they appear in Flash, there should not be any spaces surrounding the commas.

=Example= On a USB dongle, create the file  with the following text: 

Also on the USB dongle, create the file  with the following text:  

Insert the dongle into the chumby, and restart the Control Panel - the labels of the DONE and CANCEL buttons should reflect the new text.