14. Internationalization

14.1. Translations

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

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

Choosen translation system is set in client configuration file client_conf/client.ini:

### Internationalization ###

# I18n class
# use I18nDummy for no translation management
# use I18nGettext for gettext (will need PHP gettext module)
I18nClass = I18nDummy

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

14.1.1.2. Win32

TODO

14.1.2. PO Templates

Texts to be translated can be found in:

Smarty templates using SmartyGettext (see Section 15.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 4.1, “Translations”)

To generate PO templates, you will need to launch scripts on server and on client. Templates are generated in directory <cartoweb_home>/po. If translation files (see Section 14.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
./server2pot.php
```
For each mapfile, two templates will be generated: server-<project_name>.po and server-<project_name>.<mapfile_name>.po
generate project template on client:
```
cd <cartoweb_home>/scripts
./client2pot.php
```
For each project, one template will be generated: client-<project_name>.po

14.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 default project will have three PO files for a complete french translation:

server-default.po
server-default.test.po
client-default.po

14.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
./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.

14.1.5. Example

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

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

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