[Chameleon] Adding a new language

[Bart van den Eijnden]

Hi Dejan,

Chameleon 2.2 and before that used dbf files per widget, to add a language one would simply add a column to all of the dbf files, e.g. for Dutch we added NL_NL.

Currently (Chameleon CVS), the MLT system uses php include files, see also the attached guide which was written by Bill Bronsema of DMSG.

If you are gonna do this effort, I would recommend using the CVS version, and not Chameleon 2.2.

Best regards,
Bart

Bart van den Eijnden
Syncera IT Solutions
Postbus 270
2600 AG  DELFT

tel.nr.: 015-7512436
email: BEN at Syncera-ITSolutions.nl

>>> "Dejan Gambin" <dejan.gambin at pula.hr> 19-11-2005 22:27 >>>
Hi,

I am planning to use Chameleon, but I am interested in how to add a new
language (croatian). I am pretty newbie in Chameleon so I am a little bit
confused. There are some dbf files and there are some txt files in cvs that
are used by MLT...

Can somebody explain me how to do this or is it something changing in
language handling so I have to use CVS or what?

Thanks very much

Dejan Gambin

_______________________________________________
Chameleon mailing list
Chameleon at lists.maptools.org 
http://lists.maptools.org/mailman/listinfo/chameleon

-------------- next part --------------
MLT for Chameleon Developers
----------------------------


MLTPHPInclude Overview
----------------------
The MLTPHPInlcude class object was created to work with a text file to enumerate resources.  Text file format was chosen to simplify the merging and managing of multiple languages.  Each language is in a separate text file.

The format of the text file is relatively simple.  Any line that does not start with "//" and contains a ")" will be considered a valid resource.    The part of the line preceding the ")" becomes the case-sensitive index portion of the resource and the rest of the line becomes the value portion of the resource.

i.e.

// this is not a resource
1) This is a resource
2) So is this
i) and this
abcdefghij) This is also a valid resource

The MLTPHPInclude class object creates a single PHP file that gets included in the PHP script using the object.  The include file generates an internal PHP array that is accessed by the get() method.  Multiple text files can be loaded into the class object.  Resources are loaded via the loadResource() method.

The PHP include file can be cached to a temp directory to allow for faster loading next time.



Usage Inside Widgets
--------------------
The first thing to do to add language support to a widget is create the resource file.  Chameleon has been set up to automatically load resource files for a widget provided the resource file name is of the format <widget name>.<language>.txt.  i.e. ZoomIn.en-ca.txt for the English version of the ZoomIn widget.

To access the resources inside the widget, use the get() method on the "moMLT" member object of the widget.  i.e. $this->moMLT->get( 'ZoomIn', '5', 'This is my text’ ).

The get() method takes the following parameters:

$szID - The resource ID to reference.  In most of the cases, this will always be the widget’s own resources (i.e. ZoomIn resources) but any resource can be referenced here provided that is has been loaded.  In Chameleon there are a set of "core" resources and "common" resources that can be used.  To use them do something like the following:

$this->moMLT->get( 'common', 'ok', 'ok’ )

$szKey - The second parameter is the key to look up.  This is the index in the resource file.

$szDefault - The default value to return if any errors occurred or if the resource was not available.  This parameter is optional.

$aszParams - This is an array of arguments to run through the vsprintf() PHP function (http://ca3.php.net/manual/en/function.vsprintf.php) on the resource requested.  This allows the for more flexible messages to be saved as resources.  This parameter is optional.

$szLanguage - The language to return the resource in.  This parameter is optional.  If not supplied the current language will be returned.  This allows for multiple translations to be displayed in a single page.



Usage Inside Widget Popup Windows
---------------------------------
Because popup windows create their own session object, the resource file must be defined in the PHP code of the popup window prior to the session being created.  To do this, you simply set a global variable called "$szLanguageResource" to the path and filename (without extension) of the resource to load.  This is done before the inclusion of the session.inc.php file.

i.e. 
$szLanguageResource = str_replace("\\","/",dirname(__FILE__)).'/ErrorReportPopup';
include("../session.inc.php");

The session.inc.php file creates it’s own MLT object to use.  To reference resources insde the popup, simply reference the $oMLT object from the session.inc.php file.  i.e. $oMLT->get( 'common', 'Close', 'Close' ).



Caching
-------
The MLTPHPInclude class object has the ability to cache the include file.  Chameleon creates a temporary PHP include file that is stored in the temp directory.  Chameleon will create a PHP include file for each template instance.   

By default caching is turned ON.  A new configuration item has been added to the Chameleon.xml config file, it is called "cache_mlt".  Its value can be either true or false to allow caching or not.

This value can be overridden in an individual application by defining a variable called 'MLT_NOCACHE' and setting it to either true or false.  This must be done in the application prior to the creation of the Chameleon instance.

i.e.
define( 'MLT_NOCACHE', true );
class MyChameleon extends Chameleon
...



Streamlining Chameleon for Speed
--------------------------------
Some Chameleon applications do not need language translation and, as such, should not have to pay the overhead costs of the translation.  mlt.php now includes a class that can be used in place of the MLTPHPInclude such that it will only return the default value.  This class is called "MLTPHPIncludeDefault".

This class has all the same methods and member variables as the real MLTPHPInclude class, but it does not have the overhead of including and/or processing files.  It simply returns the default value.

Chameleon can be overridden to use this default mode by defining a 'MLT_DEFAULT_ONLY' variable and setting it to true or false.  It must be set in the application before creating the Chameleon instance.

i.e.

define( 'MLT_DEFAULT_ONLY', true );
class MyChameleon extends Chameleon
...