server/usr/share/psa-pear/pear/docs/horde/TRANSLATIONS

=========================
 Horde Translation Guide
=========================

:Author:  Jan Schneider <jan@horde.org>
:Author:  Chuck Hagenbuch <chuck@horde.org>
:Author:  Joris Braakman <jbraakman@yahoo.com>
:Contact: horde@lists.horde.org (for administrators)
:Contact: i18n@lists.horde.org (for translators)

.. contents:: Contents
.. section-numbering::


---------------------
 Administrator Guide
---------------------

For translator documentation see the `Translator Guide`_ below.


GNU gettext, PHP and Horde
==========================

Horde uses GNU gettext for internationalization (i18n) and localization
(l10n).  The manual at http://www.gnu.org/software/gettext/manual/gettext.html
is biased against C and using Emacs.  This is more for Horde.

There is a good explanation for PHP and gettext at:
http://www.faqts.com/knowledge-base/view.phtml/aid/2953/fid/422

People seem to like learning from examples better, so I have used dutch
(nl_NL) as an example everywhere.

There is a command line tool written in PHP for creating and managing
translations in the ``/usr/bin/`` or ``horde/bin/`` directory.  Usage
instructions can be found in the `Translator Guide`_ below as well as
instructions on how to start and maintain translations.


Translations don't work
=======================

If all or some translations don't work on your system, please follow the steps
described below.  If you want to ask for help either on the `i18n mailing
list`_ or on `Horde's bug system`_, please explain which steps you tried and
which failed.

You might also find some more information in the FAQ_.

Please note that Dutch (nl_NL) is only used as an example here.  If you have
problems with a certain translation use this translation's language code
instead. Most locales only use the language part of the locale name (the first
two lowercase letters) for the actual translation directories, i.e. ``nl`` in
this example. Prominent exceptions from this rule are Chinese (zh_TW, zh_CN)
and Brazilian Portuguese (pt_BR).

1. Is this locale (nl_NL) installed at all?

   ``locale -a`` should list all locales installed on your system.

   On Debian and Ubuntu not all locales may be enabled by default. On Debian
   edit ``/etc/locale.gen`` and run ``locale-gen`` after you changed the list
   of enabled locales. On Ubuntu run ``locale-gen nl_NL`` for all locales that
   you want to install.

2. Do you have any .mo files?

   Usually in ``/usr/share/locale/``
   e.g. ``/usr/share/locale/nl/LC_MESSAGES/tar.mo``

3. Does gettext even work?

   Get a string to translate::

      $ strings /bin/tar | grep Memory
      Memory exhausted
      $ (LANG=nl_NL; LANGUAGE=nl_NL; LC_MESSAGES=nl_NL; gettext tar "Memory exhausted" )
      Geheugen uitgeput

4. Does the local Horde file work?

   Assuming that you have put the translated Horde file in
   ``/var/www/horde/locale/nl/LC_MESSAGES/horde.mo``::

      $ TEXTDOMAINDIR=/var/www/horde/locale LANG=nl_NL.utf8 LANGUAGE=nl_NL.utf8 LC_MESSAGES=nl_NL.utf8 gettext horde "Calendar" )
      Agenda

   Create a file in the horde directory, langtest.php::

      <?php

      setlocale(LC_MESSAGES, 'nl_NL');
      putenv('LANG=nl_NL');
      putenv('LANGUAGE=nl_NL');
      // use the tar test.
      echo dgettext('tar', 'Memory exhausted');
      echo '<br />';

      // Specify location of translation tables
      bindtextdomain('horde', './locale');

      // Choose domain
      textdomain('horde');

      // Print the already tested message
      echo _("Calendar");
      echo '<br />';

      // this should print the same.
      echo dgettext('horde', 'Calendar');

      ?>

   Output web browser::

      Geheugen uitgeput
      Agenda
      Agenda


.. _`i18n mailing list`: http://www.horde.org/community/mail
.. _`Horde's bug system`: http://bugs.horde.org
.. _FAQ: http://wiki.horde.org/FAQ


Solaris
=======

Since the .mo files are binary, they are platform specific.  You have to rerun
make in all po directories.

On Solaris 7, you don't have the ``Partial Locales (SUNWploc)`` and
``Supplementary Partial Locales (SUNWploc1)`` packages installed if you get::

   $ LANG=nl_NL
   couldn't set locale correctly

On Solaris 8, you must install the local packages required for the locales you
desire (for example, you may need to install ``SUNWweuos`` for Western
European locales or ``SUNWmeaos`` for Middle Eastern locales).  The packages
are located on Software Disk 1 of 2 in the directory:
``sol_8_1001_sparc/s0/Solaris_8/Product``

This is what it should say:

Solaris 7::

   $ pkginfo | grep ploc
   system      SUNWploc       Partial Locales
   system      SUNWploc1      Supplementary Partial Locales

Solaris 8::

   $ pkginfo | grep euo
   system      SUNWceuos      Central Europe OS Support
   system      SUNWceuox      Central Europe 64-bit OS Support
   system      SUNWeeuos      Eastern Europe OS Support
   system      SUNWeeuox      Eastern Europe 64-bit OS Support
   system      SUNWneuos      Northern Europe OS Support
   system      SUNWneuox      Northern Europe 64-bit OS Support
   system      SUNWseuos      Southern Europe OS Support
   system      SUNWseuox      Southern Europe 64-bit OS Support
   system      SUNWweuos      Western Europe OS Support
   system      SUNWweuox      Western Europe 64-bit OS Support

The stuff is installed in ``/usr/lib/locale``::

   $ ls /usr/lib/locale/nl
   LC_COLLATE   LC_CTYPE     LC_MESSAGES  LC_MONETARY  LC_NUMERIC   LC_TIME      nl.so.1

It was reported that the HTTP server has to be linked to the same libintl.so
file as PHP on Solaris.  Also, it may be required that libintl.so be loaded
before libc is loaded.  If you are having conflicts, you may be able to reside
them by starting apache with one of the following commands::

   $ LD_PRELOAD=libintl.so apachectl start


FreeBSD
=======

You also need UTF-8 support in FreeBSD.  This is not installed by default in
FreeBSD versions before 5.3, you need to install the
``utf8locale-without-swidth-040319`` package or port in older versions.


------------------
 Translator Guide
------------------


Translation Tool
================

``horde-translation`` 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`_. This is also the right place for new translations and general
discussions of i18n and l10n questions and problems.

``horde-translation`` is installed to your ``/usr/bin/`` directory by default,
if using PEAR to install Horde. Otherwise it's located in ``horde/bin/``

For a list of available commands run::

  horde-translation help

For detailed help on a certain command run::

  horde-translation help command

Additional information about creating translations and fixing problems can be
found in the `Administrator Guide`_.

.. _i18n mailing list: http://www.horde.org/community/mail

Prerequisites
~~~~~~~~~~~~~

To run this script you'll need a PHP command line executable with `gettext
support`_ compiled in, and the basic `PEAR`_ libraries. The script expects
your PHP executable to be in the binary search path. If your PHP executable
cannot be found, either edit the first line of ``translation`` to reflect your
location or call the script like::

  /usr/local/bin/php translation.

You'll need the `gettext`_ package version 0.12 or greater.

You'll need the PEAR packages `Console_Getopt`_ 0.11 or greater,
`Console_Table`_ and `File_Find`_. To install all needed packages, run::

  pear upgrade PEAR Console_Getopt
  pear install Console_Table File_Find

or download the newest package from the `PEAR`_ server and install them
manually in your PEAR directory.

.. _gettext support: http://www.php.net/gettext/
.. _gettext: http://www.gnu.org/software/gettext/
.. _PEAR: http://pear.php.net/
.. _Console_Getopt: http://pear.php.net/package/Console_Getopt/
.. _Console_Table: http://pear.php.net/package/Console_Table/
.. _File_Find: http://pear.php.net/package/File_Find/

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 ``locale`` directories that you can use if you have troubles
extracting the messages, though these templates might be slightly
outdated. Run::

  horde-translation extract

You now have to create a new PO file for your language. 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``. Only some languages require to specify the complete
locale name, like Chinese (``zh_CN`` or ``zh_TW``). If you want to provide a
country-specific language variant, e.g Brazilian Portuguese (``pt_BR``) or
Canadian French (``fr_CA``) you need to use the full locale too. All other
languages should only use the ``ll`` part of the locale as a parameter for the
``translation`` script.

  horde-translation init -l ll

Now you can start the translation by editing the created
``locale/ll/LC_MESSAGES/[modulename].po`` files. You should fill out the the
complete header of the created PO file, e.g.::

  # Dutch translation for Horde.
  # Copyright 2004-2017 Horde LLC (http://www.horde.org/)
  # This file is distributed under the same license as the Horde package.
  # Joris Braakman <jbraakman@yahoo.com>, 2004.
  #
  msgid ""
  msgstr ""
  "Project-Id-Version: Horde 4.0\n"
  "Report-Msgid-Bugs-To: dev@lists.horde.org\n"
  "POT-Creation-Date: 2004-04-14 10:30+0200\n"
  "PO-Revision-Date: 2004-04-14 17:17+02:00\n"
  "Last-Translator: Joris Braakman <jbraakman@yahoo.com>\n"
  "Language-Team: i18n@lists.horde.org\n"
  "MIME-Version: 1.0\n"
  "Content-Type: text/plain; charset=UTF-8\n"
  "Content-Transfer-Encoding: 8-bit\n"

To compile the translations to a binary format run::

  horde-translation make -l ll

After you created the new translation you have to add entries for this locale
in the configuration file horde/config/nls.php.

If you create a new translation for a certain module but there are already
translations for the same language for other modules, then you should use a
compendium. This will save you a lot of time and it will make translations
much more consistent.

.. _ISO 639: http://www.loc.gov/standards/iso639-2/
.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/index.html

Compendiums
~~~~~~~~~~~

This tool utilizes 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 compendiums will be used in the background without
much intervention required. But you have to create and edit a compendium
before you can use it.

To create a compendium of all existing translations for a certain locale run::

  horde-translation compendium -l ll

The ``compendium.po`` being created will contain all modules' translations of
this locale merged into a single file. You should take a closer look at this
file because you may find 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 translations for
the same strings. You can always recreate your compendium with the above
command.

If you're maintaining translations for different `branches`_ and assumed that
you have all modules of the development branch in one directory and all of the
stalbe branch in another, you probably want to share a compendium between
these directories.

To do this, you should first create a compendium in the stable branch, review
it and fix all translations until you're happy with the results. Then create a
second compendium in the head branch and include 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
development branch for both branches. To do so, use the ``-c`` or
``--compendium`` option to specify a path to your compendium.

If you translate directly from a git checkout, this is usually not necessary
because you work with all branches in the same directory and simply switch
between them with ``git checkout``.

.. _branches: http://www.horde.org/development/modules

Updating translations
~~~~~~~~~~~~~~~~~~~~~

The process of updating translations is a cycle where you extract new gettext
strings from the sources, translate those new strings or update the already
translated strings and compile them after.

To update the translation for a module, run::

  horde-translation update -m modulename -l ll

This extracts the new strings from the sources and tries to update them from
already existing translations in the compendium. You just have to translate
all untranslated strings in the ``modulename.po`` file in the
``locale/ll_CC/LC_MESSAGES`` directory of the module you updated.

If extracting new strings fails for some reason, you can use the provided
``.pot`` file instead to update your translation::

  horde-translation merge -m modulename -l ll

If your compendium is in a different directory than the ``translation``
script, you can specify the path to the compendium::

  horde-translation update -m modulename -l ll -c /path/to/compendium

Once this is done, you can compile the translation by calling::

  horde-translation make -m modulename -l ll

Extending existent translations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To have your own string (e.g. that you added to config files) displayed in
several languages, you have to

  1. specify your texts as gettext arguments, in English, e.g. by using the
     _() function or Horde_Translation methods.
  2. edit the translation files for the required national languages,
  3. compile those translation files.

Be sure to keep records of your extensions, as you will probably have to
repeat steps 2 and 3 after the next update.

E.g., you plan to offer two IMAP servers to select from in the Webmail login
screen:

  1. In ``horde/imp/config/servers.php``, you specify::

       $servers['Central'] = array(
          'name' => _("Central Mail Service"),
       ...
       $servers['CompSci'] = array(
          'name' => _("Mail Service of Computer Science Dpt.")
       ...

  2. In ``horde/imp/locale/de/imp.po`` you add two entries::

       msgid "Central Mail Service"
       msgstr "Zentraler Mailserver"

       msgid "Mail Service of Computer Science Dpt."
       msgstr "Mailserver Informatik"

     Likewise, you amend the translation files for other languages, as needed.

  3. You compile the translations using the commands::

       horde-translation make --module imp --no-compendium

"Raw" gettext strings
~~~~~~~~~~~~~~~~~~~~~

Horde provides a non-standard way to define a translatable string without
having that string translated in the code.  By using the Horde_Translation::r()
method, the string will be marked as a translatable string and extracted by the
Horde translation script, but the string will not be altered in the PHP code.
Example::

  // For a Horde package named Horde_Foo::
  $str = Horde_Translation_Foo::r("Foo");
  // -OR- For a Horde application::
  $str = Horde_Translation_Core::r("Foo");

  echo $str; // Output: Foo
  echo _($str); // Output: [Translation of 'Foo']


Access Keys
===========

Access keys, also known as shortcut keys, allow easy access to important
functions, normally by hitting the Alt/Meta key in combination with another
key. This key is marked in most user interfaces by being underlined.

As the access key is part of the word representing the action being executed,
it is in the translators responsibility to select an access key when he
translates these words. The action is always a link in Horde. The access key
of a link is selected by prefixing it with an underscore.

The help link in the menu for example is always "_Help". This means that the
"H" of the link will be underlined and the help can be opened by hitting
Alt+H. In the PO file this string will appear as::

  #: templates/menu/menu.inc:53
  msgid "_Help"
  msgstr ""

A Spanish translator might want to translate this to::

  #: templates/menu/menu.inc:53
  msgid "_Help"
  msgstr "_Ayuda"

Translators of multibyte languages need to do this a bit differently as only
ASCII characters are allowed for access keys. A Traditional Chinese translator
might want to use::

  #: templates/menu/menu.inc:53
  msgid "_Help"
  msgstr "_H說明"

This renders to "說明(H)" in the interface and you can
access this link with "H" as the access key.


Right-to-Left Languages
=======================

Translations for languages that are written from right to left might cause
unexpected behavior if parenthesis or similar characters appear inside a
translated string. To fix this broken string rendering you have to insert
special Unicode codepoints into the translated string.

Before such a string in parenthesis, add the U+202D codepoint. If there is
more right-to-left text to come after the closing parenthesis, add the U+202E
codepoint after it. If using the PO mode of the Emacs editor you can add
codepoints with the "ucs-insert" command.


Help Texts
==========

Organization of the help files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The help texts are available in the ``horde/locale/``, and
``horde/APP/locale/``, directories, where APP is any Horde application. Every
available translation is kept in a file called ``help.xml``, in a subdirectory
named according to the language name. Examples:

- Horde's original help texts are in the ``horde/locale/en/help.xml`` file.
- IMP's Brazilian help texts are in the ``horde/imp/locale/pt_BR/help.xml``
  file.

When, for any desired application and locale, there is no ``help.xml`` file
available, Horde's help system will use the application's
``locale/en/help.xml`` file, instead.

The help files must be encoded in the UTF-8 character set.

There is no compilation step involved: Every modification to, or addition of,
a ``help.xml`` file takes immediate effect.

Syntax of the help files
~~~~~~~~~~~~~~~~~~~~~~~~

Each help file must consist of syntactically valid XML code.

There are no predefined entities beyond the XML standard entities:

- &lt;   (less than)
- &gt;   (greater than)
- &amp;  (ampersand)
- &apos; (ASCII apostrophe)
- &quot; (ASCII quotation mark)

Any character available in the language's preferred character set can be
entered as a numerical character reference (based on its Unicode scalar
value), such as ``&#160;`` for the No-Break Space character.

The general structure can be learned from the existing examples; of course,
the XML tags must be syntactically valid, and properly nested.

.. Note:: A PHP error message like ``Undefined index: url in
          /var/www/horde/lib/Horde/Help.php`` means that you have mis-spelled,
          or omitted, an attribute (``url``, in this example).

The following tags are available:

+---------+--------+---------------+-------------------------------+
| XML-Tag | Parent | Attributes    | Purpose                       |
+=========+========+===============+===============================+
| help    |   —    |       —       | List of help texts            |
+---------+--------+---------------+-------------------------------+
| entry   | help   | id            | Help text                     |
+---------+--------+---------------+-------------------------------+
| title   | entry  |       —       | Entry in the help index       |
+---------+--------+---------------+-------------------------------+
| heading | entry  |       —       | Level 2 heading               |
+---------+--------+---------------+-------------------------------+
| para    | entry  |       —       | Paragraph                     |
+---------+--------+---------------+-------------------------------+
| ref     | para   | module, entry | Link into the help system     |
+---------+--------+---------------+-------------------------------+
| eref    | para   | url           | External link                 |
+---------+--------+---------------+-------------------------------+
| href    | para   | app, url      | Link into a Horde application |
+---------+--------+---------------+-------------------------------+
| b       | para   |       —       | Bold text                     |
+---------+--------+---------------+-------------------------------+
| i       | para   |       —       | Italic text on new line       |
+---------+--------+---------------+-------------------------------+
| pre     | entry  |       —       | Example box                   |
+---------+--------+---------------+-------------------------------+
| tip     | entry  |       —       | Tip/hint box                  |
+---------+--------+---------------+-------------------------------+
| warn    | entry  |       —       | Warning box                   |
+---------+--------+---------------+-------------------------------+

The elements marked ``para``, in the Parent column, may also be used within
``pre``, ``tip``, and ``warn`` elements.

The following attributes are available:

+---------+-----------+----------------------------------+
| XML-Tag | Attribute | Purpose/Syntax                   |
+=========+===========+==================================+
| entry   | id        | Anchor                           |
+---------+-----------+----------------------------------+
| ref     | module    | Index of Horde application, see  |
|         |           | ``horde/config/registry.php``    |
|         +-----------+----------------------------------+
|         | entry     | Id of help file entry, see above |
+---------+-----------+----------------------------------+
| eref    | url       | arbitrary URL                    |
+---------+-----------+----------------------------------+
| href    | app       | Index of Horde application, see  |
|         |           | ``horde/config/registry.php``    |
|         +-----------+----------------------------------+
|         | url       | URL within Horde application     |
+---------+-----------+----------------------------------+

Examples::

  <ref module="imp" entry="compose-attachments">selecting attachments</ref>
  <eref url="http://wiki.horde.org/FAQ/User/IMP?referer=FAQ/User#toc17">
        UW-IMAP quirk</eref>
  <href app="turba" url="search.php">Address search</href>

The `Translation Tool`_ will introduce additional attributes:

+---------+-----------+--------------------------------+
| XML-Tag | Attribute | Purpose/Syntax                 |
+=========+===========+================================+
| entry   | state     | See `Finishing a translation`_ |
|         +-----------+--------------------------------+
|         | md5       | Used internally                |
+---------+-----------+--------------------------------+

Reference from the Horde applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The typical incantation, e.g.::

  <?php echo Horde_Help::link('imp', 'compose-buttons') ?>

will yield a link, adorned with the ``help.png`` icon, to the entry marked
``id="compose-buttons"`` in the IMP help file pertaining to the user's current
locale. Usually, these links are placed in the template files, next to the
item to be explained by the pertinent help entry.

The Horde menu will usually contain a general help item, which is generated in
``lib/Horde/Menu.php``.

Creating a new translation
~~~~~~~~~~~~~~~~~~~~~~~~~~

If necessary, define a suitable language name. E.g., if you plan to add an
Austrian translation, you would use ``de_AT`` as your language name.

For Horde, and for all relevant applications, copy the ``help.xml`` files from
the ``locale/en/`` subdirectories to the ``locale/ll/`` subdirectories,
creating them if necessary.

Translate each new ``locale/ll/help.xml`` file, leaving all tags and
attributes unchanged. Just translate the text between the tags.

.. Important:: The ``id`` attributes must be kept unchanged, under any
               circumstances.

If the application is already translated and only the help files are missing,
then be sure to use the same terminology as the existing translation. In any
case, try to use a lucid, coherent terminology.

Finishing a translation
~~~~~~~~~~~~~~~~~~~~~~~

If you want to submit a translation to be included in the Horde code base,
make sure that you have completed all translations. Then run::

  horde-translation make-help -l ll

This will mark all entries as being up-to-date so that you or other
translators can later see which entries have been changed since then.

Updating an existing translation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run::

  horde-translation update-help -l ll

This will merge your existing help file with all changes from the original,
English help file since your last translation. Changed entries are marked with
the attribute ``state="changed"``, new entries with ``state="new"``. The
original entry from the English help file is added in a comment below a
changed entry, so that you can easily compare them.

Translate the remaining English phrases, like discussed above. When your
finished, remove any English entries and follow the steps at `Finishing a
translation`_.

Extending existent translations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you feel that some feature should be better explained to the end user, then
proceed as following:

1. Determine, whether you will have to extend an existing entry, or add a new
   one.

2. In the latter case, choose a suitable ``id`` for your new help entry.

3. Edit the existing entry in, or add a new entry to, the application's
   ``en/help.xml`` file. Change all translations needed in your site in the
   same way. Be sure to use the same ``id`` everywhere.

4. If you have added a new entry, you might want to add a link to it from a
   template, as explained above in `Reference from the Horde applications`_.

5. If you feel that your enhancement may be useful to other users, file an
   enhancement request at http://bugs.horde.org/ with a patch including your
   changes to the template and the ``help.xml`` files.

6. In any case, keep notes of your changes, so you can apply them to later
   versions if necessary.