[Sommaire] [Imprimer]

   1  ===================
   2   Translation Guide 
   3  ===================
   4  
   5  :Date:     $Date: 2006/07/26 14:06:51 $
   6  :Revision: $Revision: 1.29.4.1 $
   7  :Authors:  Jan Schneider
   8  :Contact:  i18n@lists.horde.org
   9  
  10  .. contents::
  11  .. section-numbering::
  12  
  13  Translation Tool
  14  ================
  15  
  16  ``translation.php`` is a small PHP script that should help translators doing
  17  their work.
  18  Any feedback, bug reports and feature requests should be send to the `i18n
  19  mailing list`_. This is also the right place for new translations and general
  20  discussions of i18n and l10n questions and problems.
  21  
  22  For a list of available commands run::
  23  
  24    ./translation.php help
  25  
  26  For detailed help on a certain command run::
  27  
  28    ./translation.php help command
  29  
  30  Additional information about creating translations and fixing problems can be
  31  found in the file ``horde/docs/TRANSLATION``.
  32  
  33  .. _i18n mailing list: http://horde.org/mail/
  34  
  35  Prerequisites
  36  ~~~~~~~~~~~~~
  37  
  38  To run this script you'll need a PHP executable like the CLI or the CGI version
  39  with `gettext support`_ compiled in and the basic `PEAR`_ libraries. The
  40  script expects your PHP executable to be at ``/usr/bin/php``. If your
  41  executable is at another place, either edit the first line of
  42  ``translation.php`` to reflect your location or call the script like::
  43  
  44    /usr/local/bin/php -f translation.php.
  45  
  46  You'll need `gettext`_ 0.11 or greater, but version 0.12 or greater is strongly
  47  recommended as this is the first version that supports PHP natively. Older
  48  versions may not extract all translateable strings correctly.
  49  A windows version of the gettext binaries can be found on every `GNU ftp
  50  mirror`_ as of version 0.12.
  51  
  52  You'll need the PEAR packages `Console_Getopt`_ 0.11 or greater,
  53  `Console_Table`_ and `File_Find`_. To install all needed packages, run::
  54  
  55    pear upgrade PEAR Console_Getopt
  56    pear install Console_Table File_Find
  57  
  58  or download the newest package from the `PEAR`_ server and install them
  59  manually in your PEAR directory.
  60  
  61  .. _gettext: http://www.gnu.org/software/gettext/
  62  .. _gettext support: http://www.php.net/gettext/
  63  .. _GNU ftp mirror: http://www.gnu.org/prep/ftp.html
  64  .. _PEAR: http://pear.php.net/
  65  .. _Console_Getopt: http://pear.php.net/package/Console_Getopt/
  66  .. _Console_Table: http://pear.php.net/package/Console_Table/
  67  .. _File_Find: http://pear.php.net/package/File_Find/
  68  
  69  Creating a new translation
  70  ~~~~~~~~~~~~~~~~~~~~~~~~~~
  71  
  72  To create a new translation you first have to extract all gettext messages from
  73  the PHP sources. There are already template files with the ``.pot`` suffix in
  74  the ``po`` directories that you can use if you have troubles extracting the
  75  messages but they might be outdated.
  76  Run::
  77  
  78    ./translation.php extract
  79  
  80  You now have to create a new PO file for your locale. A locale has the form
  81  ``ll_CC`` where ``ll`` is the two letter `ISO 639`_ code of the language and
  82  ``CC`` the two letter `ISO 3166`_ code of the country, e.g. ``de_DE``,
  83  ``en_US`` or ``pt_BR``.
  84  ``translation.php`` is able to guess the locale from the ``LANG`` environment
  85  variable but it is safer to specify the locale with the ``-l`` parameter.
  86  To create the PO file run::
  87  
  88    ./translation.php init -l ll_CC
  89  
  90  Now you can start the translation by editing the created ``ll_CC.po``
  91  files. It is important to set the correct charset for the locale in the
  92  ``Content-Type:`` header.
  93  You should fill out the the complete header of the created ``ll_CC.po`` file,
  94  e.g.::
  95  
  96    # Dutch translation for Horde.
  97    # Copyright (C) 2004 Horde Project
  98    # This file is distributed under the same license as the Horde package.
  99    # Joris Braakman <jbraakman@yahoo.com>, 2004.
 100    #
 101    msgid ""
 102    msgstr ""
 103    "Project-Id-Version: Horde 2.3\n"
 104    "Report-Msgid-Bugs-To: dev@lists.horde.org\n"
 105    "POT-Creation-Date: 2004-04-14 10:30+0200\n"
 106    "PO-Revision-Date: 2004-04-14 17:17+02:00\n"
 107    "Last-Translator: Joris Braakman <jbraakman@yahoo.com>\n"
 108    "Language-Team: i18n@lists.horde.org\n"
 109    "MIME-Version: 1.0\n"
 110    "Content-Type: text/plain; charset=ISO-8859-1\n"
 111    "Content-Transfer-Encoding: 8-bit\n"
 112  
 113  To compile the translations to a binary format run::
 114  
 115    ./translation.php make
 116  
 117  After you created the new translation you have to add entries for this locale
 118  in the configuration file horde/config/nls.php.
 119  
 120  TODO: filling new po files with strings from the compendium.
 121  
 122  .. _ISO 639: http://www.loc.gov/standards/iso639-2/
 123  .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/index.html
 124  
 125  Maintaining translations
 126  ~~~~~~~~~~~~~~~~~~~~~~~~
 127  
 128  This tool is designed to help you translators doing your great work. It changes
 129  a lot compared to the old methods creating and maintainig your translations. To
 130  make the transition to the tool as smooth as possible you should read chapter
 131  3.1 before using this tool the first time.
 132  
 133  First time use of translation.php
 134  ---------------------------------
 135  
 136  This tool introduces a nice feature of gettext: compendium files. A compendium
 137  is a special PO file containing a set of translations recurring in many
 138  different packages. These compendia will be used in the background without much
 139  for you to care about. But you have to create and edit a compendium before you
 140  can use it.
 141  
 142  To create a compendium of all your existing translations run::
 143  
 144    ./translation.php compendium -l ll_CC
 145  
 146  The ``compendium.po`` being created will contain all modules' translations of
 147  this locale merged into a single file. You should take a closer look at this
 148  file because you may find a lot of special marked lines where you translated
 149  certain strings differently in the various modules. It's a good idea to fix
 150  the modules' translations now so that all modules use the same translation for
 151  the same string. You can always recreate your compendium with the above
 152  command.
 153  
 154  If you're maintaining translations for different `branches`_ and assumed that
 155  you have all modules of the ``HEAD`` branches in one directory and all of the
 156  ``RELENG_*`` branches in another, you probably want to share a compendium
 157  between these directories.
 158  
 159  You should first create a compendium in the ``RELENG_*`` branch, review it and
 160  fix all translations until you're happy with the result. Then create a second
 161  compendium in the ``HEAD`` branch and include your first one with the --add
 162  option.
 163  Now fix the translations in this branch. If you're ready you can remove the
 164  first compendium and for now on use the compendium in the ``HEAD`` branch for
 165  both branches. To do so use the ``--compendium`` option to specify a path to
 166  your compendium.
 167  
 168  .. _branches: http://www.horde.org/source/
 169  
 170  Updating translations
 171  ---------------------
 172  
 173  The process of updating translations is a cycle where you extract new gettext
 174  strings from the sources, translate those new strings or update the already
 175  translated strings and compile them after.
 176  
 177  To update the translation for a module, run::
 178  
 179    ./translation.php update -m modulename -l ll_CC
 180  
 181  This extracts the new strings from the sources and tries to update them from
 182  already existing translations in the compendium. You just have to translate
 183  all unstranslated strings in the ``ll_CC.po`` file in the ``po`` directory of
 184  the module you updated.
 185  
 186  Once this is done, you can compile the translation by calling::
 187  
 188    ./translation.php make -m modulename -l ll_CC
 189  
 190  Extending existent translations
 191  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192  
 193  To have your own texts (as supplied in config files for example) displayed in
 194  several languages, you have to
 195  
 196    1. specify your texts as gettext arguments, in English,
 197    2. edit the translation files for the required national languages,
 198    3. compile those translation files.
 199  
 200  Be sure to keep records of your extensions, as you will probably have to
 201  repeat steps 2 and 3 after the next update.
 202  
 203  E.g., you plan to offer two IMAP servers to select from in the Webmail login
 204  screen:
 205  
 206    1. In ``horde/imp/config/servers.php``, you specify::
 207  
 208         $servers['Central'] = array(
 209            'name' => _("Central Mail Service"),
 210         ...
 211         $servers['CompSci'] = array(
 212            'name' => _("Mail Service of Computer Science Dpt.")
 213         ...
 214  
 215    2. In ``horde/imp/po/de_DE.po`` you add two entries::
 216  
 217         msgid "Central Mail Service"
 218         msgstr "Zentraler Mailserver"
 219         msgid "Mail Service of Computer Science Dpt."
 220         msgstr "Mailserver Informatik"
 221  
 222       Likewise, you amend the translation files for other languages, as needed.
 223  
 224    3. You compile the translations using the commands::
 225  
 226         ./po/translation.php make --module imp --no-compendium
 227  
 228  Access Keys
 229  ===========
 230  
 231  Access keys, also known as shortcut keys, allow easy access to important
 232  functions, normally by hitting the Alt/Meta key in combination with another
 233  key. This key is marked in most user interfaces by being underlined.
 234  
 235  As the access key is part of the word representing the action being executed,
 236  it is in the translators responsibility to select an access key when he
 237  translates these words. The action is always a link in Horde. The access key
 238  of a link is selected by prefixing it with an underscore.
 239  
 240  The help link in the menu for example is always "_Help". This means that the
 241  "H" of the link will be underlined and the help can be opened by hitting
 242  Alt+H. In the PO file this string will appear as::
 243  
 244    #: templates/menu/menu.inc:53
 245    msgid "_Help"
 246    msgstr ""
 247  
 248  A Spanish translator might want to translate this to::
 249  
 250    #: templates/menu/menu.inc:53
 251    msgid "_Help"
 252    msgstr "_Ayuda"
 253  
 254  Translators of multibyte languages need to do this a bit differently as only
 255  ASCII characters are allowed for access keys. A Traditional Chinese translator
 256  might want to use::
 257  
 258    #: templates/menu/menu.inc:53
 259    msgid "_Help"
 260    msgstr "_H說明"
 261  
 262  This renders to "說明(H)" in the interface and you can
 263  access this link with "H" as the access key.