< Throttling Configuration

Templating >

17. Internationalization

17.1. Translations

Translation handling in CartoWeb was designed to use gettext . However internationalization architecture is ready for other translation systems.


Scripts detailed below are only available in command line prompts ("DOS", shell). They cannot be launched using a web browser.

17.1.1. Configuration

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.

Translation system is now automatically set to gettext if gettext is installed otherwise it's disabled. Parameter I18nClass is now deprecated. Unix-like

In Unix-like environments, file /etc/locale.alias 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.

fr    fr_CH.ISO-8859-1

You will need to run locale-gen after editing /etc/locale.alias to regenerate system's locales.

To install a locale on a Debian installation, use following command with root priviledges:

dpkg-reconfigure locales

If package locales has never been installed, you have to install it before:

apt-get install locales

Two scripts have been prepared to check if gettext is correctly installed on the system:

  • scripts/testgettext.sh: This will compile and run a small C program that will test xgettext and msgfmt.
  • scripts/testgettext.php: Given that gettext was correctly installed on the system, this will test that gettext works in PHP.


These scripts need that locales have been correctly configured. They were tested on GNU/Linux with a Debian/Sarge install.


On debian etch systems locale.alias path has changed. You should find it in /usr/share/locale/locale.alias. Win32

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 Input Locales of Windows (windows 2000: Control Panel > Regional Options > Input Locales. windows XP: Control Panel > Regional and Language Options > Details > Settings)

17.1.2. PO Templates

Texts to be translated can be found in:

To generate PO templates, you will need to launch scripts on server and on client. Templates are generated in directory <cartoweb_home>/projects/<project_name>/po. If translation files (see Section 17.1.3, “Translating”) already exist, a merge is done using msgmerge command. Follow these steps:

  • generate project and mapfile templates on server:
    cd <cartoweb_home>/scripts
    php server2pot.php
    For each mapfile, two templates will be generated: server.po and server.<mapfile_name>.po
  • generate project template on client:
    cd <cartoweb_home>/scripts
    php client2pot.php
    For each project, one template will be generated: client.po

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:

php server2pot.php myprojectname

If you do not specify a project name, the .po files will be generated for all projects.

17.1.3. Translating

As for any gettext system, translating PO files can be done in Emacs, in Poedit or in any text editor.

Translated PO files must be saved under name <template_name>.<lang>.po ; where <lang> 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:

  • server.fr.po
  • server.test.fr.po
  • client.fr.po

17.1.4. Compiling PO to MO

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.

cd <cartoweb_home>/scripts
php po2mo.php

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.

17.1.5. Example

To translate texts in french for project test_project and map file projectmap, follow these steps:

  • On server:
    cd <cartoweb_home>/scripts
    php server2pot.php
    Copy <cartoweb_home>/projects/test_project/po/server.po to <cartoweb_home>/projects/test_project/po/server.fr.po and <cartoweb_home>/projects/test_project/po/server.projectmap.po to <cartoweb_home>/projects/test_project/po/server.projectmap.fr.po . Edit french files with Poedit (or any editor).
  • On client:
    cd <cartoweb_home>/scripts
    php client2pot.php
    Copy <cartoweb_home>/projects/test_project/po/server.po to <cartoweb_home>/projects/test_project/po/server.fr.po . Edit french file with Poedit (or any editor). Merge and compile files with the following commands:
    cd <cartoweb_home>/scripts
    php po2mo.php
    Now you should have the file test_project.projectmap.mo in directory <cartoweb_home>/locale/fr/LC_MESSAGES . The directory fr/LC_MESSAGES will be created if it does not exist.

17.1.6. Debuging translation problems

There can be several reasons why the translation is not working.

First you need to check if gettext is correctly installed and configured. For so run the following scripts:

  • cd <cartoweb_home>/scripts
    This will test if Gettext is correctly installed in your system


    Unix-like system only, this script is not intended for Windows users

  • cd <cartoweb_home>/scripts
    php testgettext.php
    This will test if Gettext works correctly with php

Once you have verified Gettext is installed and run correctly, check if there are no errors in your po files.

  • Verify you do no have duplicate msgid in your po files. Each msgid must be unique in a po file. A typical error message would be:
    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)
    duplicate message definition on line 392 in client.en.po
  • Check if you have several fuzzy entries in your merged 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 msgid in different po files.


    Each po file contain a single fuzzy entry at the beginning, this should not be removed

    #, fuzzy
    msgid ""
    msgstr ""
    "POT-Creation-Date: 2005-09-13 09:36+0200\n"
  • Gettext automatically comments msgid and msgstr that are not found anymore in your templates. Commented lines start with #. Sometimes this is unwelcome, simply uncomment the lines.
  • If your CartoWeb profile is set to production (Section 4.1, “Common client.ini and server.ini Options”), do not forget to clean the temporary templates files by typing:
    php cw3setup-php --clean
    See Section, “Cleaning Generated Files (Map, PDF, Temporary Files and Smarty Cache)” for more details.


    It can also be usefull sometimes in development mode.

  • 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.

17.2. Character Set Encoding Configuration

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:

  • how files (map files, configuration files, etc.) are encoded on server and on client. To set this encoding, add the following line in server.ini and in client.ini:
    EncoderClass.config = <encoder_class>
  • how source data (shapefile, database, .. must be encoded. To set this encoding, add the following line in client.ini:
    EncoderClass.data = <encoder_class>
    If not set, default to the same encoding as config, to keep backward compatibility
  • how CartoWeb exports (including HTML output) must be encoded. To set this encoding, add the following line in client.ini:
    EncoderClass.output = <encoder_class>

Where <encoder_class> is the class used for encoding. Currently, following encoder classes are implemented:

  • EncoderISO: handles strings coded in ISO-8859-1
  • EncoderUTF: handles strings coded in UTF-8

17.3. Character Set Encoding Configuration for Data Sources

When you have layers data with heterogeneous encoding (typicaly iso and utf8), you can define specific EncoderClass by layer. Simply add "data_encoding" in the METADATA section in the mapfile or in the layers.ini for the layers which need it.

The encoding used when reading data depends of the parameters set. The fallback order is:

  • data_encoding (in mapfile or layers.ini, with the corresponding EncoderClass in client.ini)(specific by layer)
  • EncoderClass.data (client.ini)(general for all layers)
  • EncoderClass.config (client.ini)(for backward compatibility)
  • UTF8 is the default if nothing is set.

See Section 6.3, “Metadata in Mapfile and layers.ini for example of usage in mapfile and layers.ini.

The EncoderClass defined in client.ini would be for example:

EncoderClass.data = EncoderUTF
EncoderClass.value_iso = EncoderISO

This example would be in the case most of your layers are in utf8 and only some are in iso.

valid xhtml 1.0 valid css