< Security Configuration

Templating >

## 16. Internationalization

## 16.1. Translations

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

### Note

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

### 16.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.

#### 16.1.1.1. 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.

### Note

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

#### 16.1.1.2. 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)

### 16.1.2. PO Templates

Texts to be translated can be found in:

- Smarty templates using SmartyGettext (see Section 17.2, “Internationalization”)
- Client plugins .ini files (for instance map sizes)
- Server plugins .ini files (for instance scales labels)
- Mapfile's .ini and .map (layers labels)
- Client and server PHP code (see Section 5.1, “Translations”)

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

### 16.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`

### 16.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.

### 16.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.

### 16.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
      ./testgettext.sh

  This will test if Gettext is correctly installed in your system

  ### Note

  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.

  ### Note

  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 1.1.3.2.4, “Cleaning Generated Files (Map, PDF, Temporary Files and Smarty Cache)” for more details.

  ### Note

  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.

## 16.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 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