==================
TRANSLATING PHPESP
==================

This document contains a guide to using phpESP in a language other than
English.


USING TRANSLATIONS
------------------

The phpESP package uses GNU gettext to support multiple languages.  GNU
gettext support must be available in PHP for this feature to be
available.  PHP may either be compiled with gettext support, or the
gettext extension may be loaded at run-time.  To compile PHP with
gettext support you must use the --with-gettext configure option.  To
load the gettext extension at run time, simply place the gettext
extension in the PHP extension directory; phpESP will automatically
load the extension.  Alternatively, you may edit the php.ini and have
PHP load the extension when it starts; you may have to do this if PHP
safe_mode is enabled.  The php.ini directive to load an extension is
'extension,' for example, to load gettext on a Unix system you would
need 'extension gettext.so' in the php.ini.  Refer to the PHP
documentation for more details on the PHP gettext extension, and
loading extensions.

The phpESP system test page will indicate weather GNU gettext is
available.  If the test reports GNU Gettext as 'Emulated,' then only
the native language (English) will be available.  If it is reported as
'Real' and the test is reported as 'Passed,' any existing translation
will be available.  If the test fails, and support is 'Real,' please
send a bug report along with the entire system test page.

The language used for the administrative interface, and the survey
designer is determined by your browser preferences.  phpESP will choose
the closest language to the language preferences indicated by your
browser.  You may also set the default language in the phpESP.ini.php,
which will be used for browsers that do not indicate language
preference, or when no matching translation is available.


ADDING TRANSLATIONS
-------------------

There are several tools to work with gettext message catalogs.  It may
be worth investigating what tools are available for your platform
before beginning the task of translation.  The message catalogs are
plain text, so no tools other than your favorite editor are required.

There is an experimental PHP script available for creating and
maintaining the phpESP translations online, if you do not find any
suitable tools for your platform.  Please contact the developers via
the developer mailing list for more information.

The message catalogs are stored in the phpESP/locale/ directory.  Here
you will find a subdirectory for each locale to which phpESP has been
translated.  In each locale directory, is a directory called
LC_MESSAGES/ which contains two files: messages.po and messages.mo. 
The 'po' file is the plain text message catalog, and the 'mo' file is a
compiled, binary form of the former.  To edit or create translations,
simply edit the appropriate messages.po file.  To start a new
translation, make a copy of the English message catalog (the en_US
locale), and proceed from there.  Completed or updated catalogs should
be sent via email to the phpESP developer list, or sent as a patch
thought the SourceForge tracker for phpESP.  Please include your name
and email when sending catalogs so appropriate credit can be given.

Locale names should consist of 'll_TT', where 'll' is the two letter
language code [ISO 639], and 'TT' is the territory (country) code [ISO
3166].


TRANSLATION PROBLEMS
--------------------

If you have translation problems or questions, please post a message to
either of the phpESP mailing lists.

----
$Id$