============================
Localizing GeoPrisma
============================

Localization can be accomplished in a number of ways, which all have one thing in common : associate a message string with a language-dependent translation string.  In GeoPrisma, we have chosen the `GNUGetText <http://en.wikipedia.org/wiki/GNU_gettext>`_ format for localization.  As you will find out reading the Wikipedia article mentioned previously, translations are held in templates (.pot files).  Human-readable strings are stored in so-called catalogs (.po files) that can be edited by a very handy cross-platform utility like `poEdit <http://www.poedit.net/>`_ [#Ed]_.  Those .po files are then compiled into .mo files and it is those .mo files that are used by PHP.

The org_geoprisma_widget_WidgetBase abstract class defines a getText function.  That function is then overloaded in specific widgets.  For example, here is the code for the GeoExtToolbar widget :

.. code-block:: php
    
    <?php

    class GeoExtToolbar extends org_geoprisma_widget_WidgetBase
    {
         static public function getText($pstrMsg, $pstrType = null)
         {
            return parent::getText($pstrMsg, self::getType(), $pstrType);
         }
         
         ...
         
         static public function getType()
         {
            return 'geoexttoolbar';
         }
    }
    
    ?>

One can see here that the implmentation of the getText function for the GeoExtToolbar widget defines a domain name (second argument) called geoexttoolbar.  That is, GeoPrisma will look for strings passed to the getText function of that widget in a file called geoexttoolbar.po in the language directory.  Looking at the structure of the languages directory, it will become apparent that templates are held at the root of the languages directory and that translations (.po/.mo) files are held further down in the directory hierarchy.

So localizing a widget amounts to overloading the getText function for the widget and giving the widget a domain name that can be used to store message strings.  

.. [#Ed] A .po file editor like poEdit will ease the task of maintaining translation strings, as it allows synching a .po file with the master (.pot) file and compiles .po files into the .mo files used by PHP on save.  New message strings can be created in the POT file using a plain text editor and then the po files for each language can be synched with poEdit, which will then show the list of strings in the catalog that need a translation.