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.
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.
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.
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)
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
andserver.<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.
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
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.
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 filetest_project.projectmap.mo
in directory<cartoweb_home>/locale/fr/LC_MESSAGES
. The directoryfr/LC_MESSAGES
will be created if it does not exist.
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 systemNote
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
andserver.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.
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 inclient.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-1EncoderUTF
: handles strings coded in UTF-8