===================================
|| Translation Helper User Guide ||
===================================

1 Introduction
1.1 Prerequisites
2 Creating a new translation
3 Maintaining translations
3.1 First time use of translation.php
3.2 Updating translations

1 Introduction
===============

translation.php is a small PHP script that should help translators doing their
work.
Any feedback, bug reports and feature requests should be send to the i18n
mailing list. See http://horde.org/mail/ for details. This is also the right
place for new translations and general discussions of i18n and l10n questions
and problems.

For a list of available commands run:
  ./translation.php help
For detailed help on a certain command run:
  ./translation.php help command

Additional information about creating translations and fixing problems can be
found in the file horde/docs/TRANSLATIONS.

1.1 Prerequisites
==================

To run this script you'll need a PHP executable like the CLI or the CGI version
with gettext support compiled in and the basic PEAR libraries. The script
expects your PHP executable to be at /usr/bin/php. If your executable is at
another place, either edit the first line of translation.php to reflect your
location or call the script like: /usr/local/bin/php -f translation.php.

You'll need gettext 0.11 or greater, but version 0.12 or greater is strongly
recommended as this is the first version that supports PHP natively. Older
versions may not extract all translateable strings correctly.
A windows version of the gettext binaries can be found on every GNU ftp
mirror as of version 0.12.

You'll need the PEAR package Console_Getopt 0.11 or greater. The package that
comes with PHP less than 4.3.0 has bugs and is not sufficient. Console_Getopt
0.11 needs also a newer PEAR than the one that comes with PHP versions prior to
4.3.0. To install new PEAR and Console_Getopt packages, run "pear upgrade PEAR"
and "pear upgrade Console_Getopt" or download the newest package from
http://pear.php.net/get/PEAR and http://pear.php.net/get/Console_Getopt and
install them manually in your PEAR directory.

All modules should be in directories under the horde directory or the script
won't be able to find them.

2 Creating a new translation
=============================

To create a new translation you first have to extract all gettext messages from
the PHP sources. There are already template files with the .pot suffix in the po
directories that you can use if you have troubles extracting the messages but
they might be outdated.
Run:
  ./translation extract

You now have to create a new PO file for your locale. A locale has the form
ll_CC where ll is the two letter ISO 639 code of the language and CC the two
letter ISO 3166 code of the country, e.g. de_DE, en_US or pt_BR.
translation.php is able to guess the locale from the LANG environment variable
you have set but it is safer to specify the locale with the -l parameter.
To create the PO file run:
  ./translation init -l ll_CC

Now you can start the translation by editing the created ll_CC.po files. It is
important to set the correct charset for the locale in the Content-Type: header.

To compile the translations to a binary format run:
  ./translation make

After you created the new translation you have to add entries for this locale in
the configuration file horde/config/lang.php (in the release version or a CVS
checkout of the RELENG_2 branch) or in horde/config/nls.php (in a CVS checkout
of the HEAD branch).

TODO: filling new po files with strings from the compendium.

3 Maintaining translations
===========================

This tool is designed to help you translators doing you great work. It changes a
lot compared to the old methods creating and maintainig your translations. To
make the transition to the tool as smooth as possible you should read chapter
3.1 before using this tool the first time.

3.1 First time use of translation.php
======================================

This tool introduces a nice feature of gettext: compendium files. A compendium
is a special PO file containing a set of translations recurring in many
different packages. These compendia will be used in the background without much
you have to care about. But you have to create and edit a compendium before you
can use it.

To create a compedium of all your existing translations run:
  ./translation.php compendium -l ll_CC

The compendium.po file now created will contain all modules' translations of
this locale merged in one file. You should take a close look at this file
because you may found a lot of special marked lines where you translated certain
strings differently in the various modules. It's a good idea to fix the modules'
translations now so that all modules use the same translation for the same
string. You can alway recreate your compendium with the above command.

Once your happy with your compendium you should never need to run the compendium
command again.

If you're maintaining translations for different branches and assumed that you
have all modules of the HEAD branches in one directory and all of the RELENG_*
branches in another, you probably want to share a compendium between those
directories.

You should first create a compendium in the RELENG_2 branch, review it and fix
all translations until you're happy with the result. Then create a second
compendium in the HEAD branch including your first one with the --add option.
Now fix the translations in this branch. If you're ready you can remove the
first compendium and for now on use the compendium in the HEAD branch for both
branches. To do so use the --compendium option to specify a path to your
compendium.

3.2 Updating translations
=========================

TODO


$Horde: horde/po/README,v 1.20 2003/05/26 09:45:36 jan Exp $
