<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
  ]>
<!-- $Id: i18n.xml,v 1.22 2007-05-25 15:43:36 pgiraud Exp $ -->
<chapter id="user.i18n">
    <title>Internationalization</title>
    <sect1 id="user.i18n.translations">
        <title>Translations</title>
        <para> Translation handling in &cartoweb; was designed to use <ulink
                url="http://www.gnu.org/software/gettext/manual">gettext</ulink>
            . However internationalization architecture is ready for other translation
            systems.</para>
        <note>
            <para>Scripts detailed below are only available in command line prompts ("DOS", shell).
            They cannot be launched using a web browser.</para>
        </note>
        <sect2 id="user.i18n.translations.config">
            <title>Configuration</title>
            <para> For now only gettext translation system is implemented. If gettext is not
                installed, you can use a dummy translation system which translates
                nothing. To use gettext, you will need to have PHP gettext module
                installed.</para>
            <para>Translation system is now automatically set to gettext if gettext is
                installed otherwise it's disabled. Parameter
                <emphasis>I18nClass</emphasis> is now deprecated. </para>
            <sect3 id="user.i18n.translations.config.linux">
                <title>Unix-like</title>
                <para>In Unix-like environments, file
                    <filename>/etc/locale.alias</filename> contains aliases to
                    installed locales. For each language used, a line must be present in
                    this file. The alias ('fr' in the example below) must point to a locale
                    installed on the system.</para>
                
                <programlisting><![CDATA[...
fr    fr_CH.ISO-8859-1
...]]></programlisting>
                <para>You will need to run <command>locale-gen</command> after editing
                    <filename>/etc/locale.alias</filename> to regenerate system's
                    locales. </para>
                <para> To install a locale on a Debian installation, use following command
                    with root priviledges:</para>
                
                <screen><![CDATA[dpkg-reconfigure locales]]></screen>
                <para>If package locales has never been installed, you have to install it
                    before:</para>
                
                <screen><![CDATA[apt-get install locales]]></screen>
                <para>Two scripts have been prepared to check if gettext is correctly installed
                    on the system:</para>
                
                <itemizedlist>
                    <listitem>
                        <para> <filename>scripts/testgettext.sh</filename>: This
                            will compile and run a small C program that will test
                            <command>xgettext</command> and
                            <command>msgfmt</command>.</para>
                    </listitem>
                    <listitem>
                        <para> <filename>scripts/testgettext.php</filename>: Given
                            that gettext was correctly installed on the system, this will
                            test that gettext works in PHP.</para>
                    </listitem>
                </itemizedlist> <note>
                <para>These scripts need that locales have been correctly configured.
                    They were tested on GNU/Linux with a Debian/Sarge install.</para>
                </note>
                
            </sect3>
            <sect3 id="user.i18n.translations.config.win32">
                <title>Win32</title>
                <para>In order to have the language translation working correctly in
                    Cartoweb with Gettext, you need to have the languages you want to use
                    installed in the <emphasis>Input Locales</emphasis> of Windows
                    (windows 2000: Control Panel > Regional Options > Input Locales.
                    windows XP: Control Panel > Regional and Language Options > Details >
                    Settings)</para>
            </sect3>
        </sect2>
        <sect2 id="user.i18n.translations.template">
            <title>PO Templates</title>
            <para> Texts to be translated can be found in: </para>
            <itemizedlist>
                <listitem>
                    <para> Smarty templates using <ulink 
                            url="http://sourceforge.net/projects/smarty-gettext/">
                        SmartyGettext</ulink> (see <xref
                            linkend="user.template.i18n"/>)</para>
                </listitem>
                <listitem>
                    <para> Client plugins .ini files (for instance map sizes) </para>
                </listitem>
                <listitem>
                    <para> Server plugins .ini files (for instance scales labels) </para>
                </listitem>
                <listitem>
                    <para> Mapfile's .ini and .map (layers labels) </para>
                </listitem>
                <listitem>
                    <para> Client and server PHP code (see <xref
                            linkend="dev.i18n.translations"/>) </para>
                </listitem>
            </itemizedlist>
            <para> To generate PO templates, you will need to launch scripts on server and on
                client. Templates are generated in directory
                <filename>&lt;cartoweb_home&gt;/projects/&lt;project_name&gt;/po</filename>. If translation files
                (see <xref linkend="user.i18n.translations.translating"/>) already
                exist, a merge is done using <ulink
                    url="http://www.gnu.org/software/gettext/manual/html_chapter/gettext_6.html#SEC37">
                <command>msgmerge</command></ulink> command. Follow these
                steps:</para>
            <itemizedlist>
                <listitem>
                    <para>generate project and mapfile templates on server:
                        
                        <screen><![CDATA[cd <cartoweb_home>/scripts
php server2pot.php]]></screen>For
                        each mapfile, two templates will be generated:
                        <filename>server.po</filename> and
                        <filename>server.&lt;mapfile_name&gt;.po</filename>
                        </para>
                </listitem>
                <listitem>
                    <para>generate project template on client:
                        
                        <screen><![CDATA[cd <cartoweb_home>/scripts
php client2pot.php]]></screen>For
                        each project, one template will be generated:
                        <filename>client.po</filename>
                        </para>
                </listitem>
            </itemizedlist>
            <para>It is possible to specify for which project you want to generate the .po
                file. Simply add the project name as a parameter when launching the scripts
                client2pot and server2pot:
                <screen><![CDATA[php server2pot.php myprojectname]]></screen> If you do
                not specify a project name, the .po files will be generated for all projects.
                </para>
        </sect2>
        <sect2 id="user.i18n.translations.translating">
            <title>Translating</title>
            <para> As for any gettext system, translating PO files can be done in Emacs, in
                    <ulink url="http://poedit.sourceforge.net/">Poedit</ulink> or
                in any text editor. </para>
            <para> Translated PO files must be saved under name
                <filename>&lt;template_name&gt;.&lt;lang&gt;.po</filename> ; where
                &lt;lang&gt; is the 2-letters ISO language: en, fr, de, etc.. For instance,
                the mapfile test of test_main project will have three PO files in its PO
                directory for a complete french translation: </para>
            <itemizedlist>
                <listitem>
                    <para> <filename>server.fr.po</filename> </para>
                </listitem>
                <listitem>
                    <para> <filename>server.test.fr.po</filename> </para>
                </listitem>
                <listitem>
                    <para> <filename>client.fr.po</filename> </para>
                </listitem>
            </itemizedlist>
        </sect2>
        <sect2 id="user.i18n.translations.compiling">
            <title>Compiling PO to MO</title>
            <para> To compile all PO files to MO files (gettext's binary format), use the
                following commands on client side. This should be done each time
                configuration (client or server) is updated, and after each system update.
                All languages are compiled at the same time.
                
                <screen><![CDATA[cd <cartoweb_home>/scripts
php po2mo.php]]></screen>
                Warning: When &cartoweb; is installed in SOAP mode, the script uses PHP curl
                functions to retrieve PO files from server to client. PHP curl module must be
                installed. </para>
        </sect2>
        <sect2 id="user.i18n.translations.example">
            <title>Example</title>
            <para> To translate texts in french for project test_project and map file
                projectmap, follow these steps: </para>
            <itemizedlist>
                <listitem>
                    <para> On server:</para>                                        
                    <screen><![CDATA[cd <cartoweb_home>/scripts
php server2pot.php]]></screen>
                    <para>Copy
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.po</filename>
                        to
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.fr.po</filename>
                        and
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.projectmap.po</filename>
                        to
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.projectmap.fr.po</filename>
                        . Edit french files with Poedit (or any editor). </para>
                </listitem>
                <listitem>
                    <para> On client:</para>                                        
                    <screen><![CDATA[cd <cartoweb_home>/scripts
php client2pot.php]]></screen>
                    <para> Copy
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.po</filename>
                        to
                        <filename>&lt;cartoweb_home&gt;/projects/test_project/po/server.fr.po</filename>
                        . Edit french file with Poedit (or any editor). </para>
                    <para> Merge and compile files with the following commands:</para>                                        
                    <screen><![CDATA[cd <cartoweb_home>/scripts
php po2mo.php]]></screen>
                    <para> Now you should have the file
                        <filename>test_project.projectmap.mo</filename> in
                        directory
                        <filename>&lt;cartoweb_home&gt;/locale/fr/LC_MESSAGES</filename>
                        . The directory <filename>fr/LC_MESSAGES</filename> will be
                        created if it does not exist. </para>
                </listitem>
            </itemizedlist>
        </sect2>
        <sect2 id="user.i18n.translations.debug">
            <title>Debuging translation problems</title>
            <para>There can be several reasons why the translation is not working.</para>
            <para>First you need to check if gettext is correctly installed and configured.
                For so run the following scripts:</para>
            <itemizedlist>
                <listitem>
                    <screen><![CDATA[cd <cartoweb_home>/scripts
./testgettext.sh]]></screen>
                    <para> This will test if Gettext is correctly installed in your system
                        <note>
                        <para>Unix-like system only, this script is not intended for
                            Windows users</para></note></para>
                </listitem>
                <listitem>
                    <screen><![CDATA[cd <cartoweb_home>/scripts
php testgettext.php]]></screen>
                    <para>This will test if Gettext works correctly with php </para>
                </listitem>
            </itemizedlist>
            <para>Once you have verified Gettext is installed and run correctly, check if
                there are no errors in your <emphasis>po</emphasis> files.</para>
            <itemizedlist>
                <listitem>
                    <para>Verify you do no have duplicate <emphasis>msgid</emphasis> in
                        your po files. Each <emphasis>msgid</emphasis> must be unique in
                        a po file.</para>
                    <para> A typical error message would be:</para>                    
                    <screen>Error message: Failure while launching "msgcat --to-code=iso-8859-1 --use-first --output=/www/cartoweb3/projects/demo/po/demo.en.po 
/www/cartoweb3/projects/demo/po/demo.en.po /www/cartoweb3/projects/demo/po/client.en.po" 
(output is /www/cartoweb3/projects/demo/po/client.en.po:392: duplicate message definition
/www/cartoweb3/projects/demo/po/client.en.po:390: ...this is the location of the first definition
msgcat: found 1 fatal error)</screen>
                    <para><emphasis>duplicate message definition</emphasis> on line
                        392 in <emphasis>client.en.po</emphasis> </para>
                </listitem>
                <listitem>
                    <para>Check if you have several <emphasis>fuzzy</emphasis> entries
                        in your <keycap>merged</keycap> po file (the file that is
                        automatically created by gettext, merging the client and server
                        po files). This happens when you have used the same
                        <emphasis>msgid</emphasis> in different po files. <note>
                        <para> Each po file contain a single <emphasis>fuzzy</emphasis>
                            entry at the beginning, this should not be removed</para>
                        <screen>...
#, fuzzy
msgid ""
msgstr ""
"POT-Creation-Date: 2005-09-13 09:36+0200\n"
...</screen></note>
                        </para>
                </listitem>
                <listitem>
                    <para>Gettext automatically comments <emphasis>msgid</emphasis>
                        and <emphasis>msgstr</emphasis> that are not found anymore in
                        your templates. Commented lines start with <keycap>#</keycap>.
                        Sometimes this is unwelcome, simply uncomment the lines.</para>
                </listitem>
                <listitem>
                    <para>If your CartoWeb profile is set to
                        <emphasis>production</emphasis> (<xref
                            linkend="user.config.common"/>), do not forget to clean
                        the temporary templates files by typing:</para>
                    <screen>php cw3setup-php --clean</screen>
                    <para>See <xref
                            linkend="user.install.main.setup.example.clean"/> for
                        more details. <note>
                        <para>It can also be usefull sometimes in
                            <emphasis>development</emphasis> mode.</para> </note>
                        </para>
                </listitem>
        <listitem>
          <para>
            If your are running PHP in a webserver as a module,
            the compiled .mo files are cached. If no change happens after compiling
            new .mo files, it could be useful to restart the webserver.
          </para>
        </listitem>
            </itemizedlist>
        </sect2>
    </sect1>
    <sect1 id="user.i18n.encoding">
        <title>Character Set Encoding Configuration</title>
        <para> Character set configuration is needed when &cartoweb; strings may include
            international characters with accents, or other special characters. Two types
            of encodings must be set: </para>
        <itemizedlist>
            <listitem>
                <para>how files (map files, configuration files, etc.) are encoded on
                    server and on client. To set this encoding, add the following line in
                    <filename>server.ini</filename> and in
                    <filename>client.ini</filename>:</para>
                
                <programlisting><![CDATA[
EncoderClass.config = <encoder_class>]]></programlisting>
            </listitem>
            <listitem>
                <para>how &cartoweb; exports (including HTML output) must be encoded. To
                    set this encoding, add the following line in
                    <filename>client.ini</filename>:</para>
                
                <programlisting><![CDATA[
EncoderClass.output = <encoder_class>]]></programlisting>
            </listitem>
        </itemizedlist>
        <para>Where &lt;encoder_class&gt; is the class used for encoding. Currently,
            following encoder classes are implemented: </para>
        <itemizedlist>
            <listitem>
                <para><classname>EncoderISO</classname>: handles strings coded in
                    ISO-8859-1 </para>
            </listitem>
            <listitem>
                <para><classname>EncoderUTF</classname>: handles strings coded in
                    UTF-8</para>
            </listitem>
        </itemizedlist>
    </sect1>
</chapter>
