docs/translation.rst

   1 ***********
   2 Translation
   3 ***********
   4
   5 DAViCAL uses the standard translation infrastructure of many projects.
   6 It is based on ``gettext`` (http://www.gnu.org/software/gettext/).
   7
   8 Translators
   9 ===========
  10
  11 Translating DAViCal
  12 -------------------
  13
  14 All translation of DAViCal is done by the Transifex tool (http://transifex.org/).
  15 We are using the Transifex service (http://www.transifex.net/) to translate the software.
  16
  17 To translate DAViCal go to http://www.transifex.net/projects/p/davical.
  18 You can register an account there and then translate DAViCal in the webbrowser to your language.
  19 Furthermore you can improve existing translations and join the team of your language.
  20
  21 Developers
  22 ==========
  23
  24 Adding translatable string to the PHP-Source
  25 --------------------------------------------
  26
  27 DAViCal currently does not use ``_()`` but has two functions to do the translation.
  28 These functions are named ``i18n()`` and ``translate()``.
  29
  30 With ``translate()`` a message can be directly translated.
  31
  32 .. code-block:: php
  33
  34    <?php
  35    print translate('TEST to be displayed in different languages');
  36
  37 In case a variable is passed all candidates can be marked by ``i18n()``.
  38
  39 .. code-block:: php
  40
  41    <?php
  42    $message_to_be_localized = i18n('TEST to be displayed in different languages');
  43    print translate($message_to_be_localized);
  44
  45 Adding context as a help for the translators
  46 --------------------------------------------
  47
  48 There are cases in which a translation might be ambigous for the translators at these places hints may be inserted.
  49
  50 Consider the following code fragment.
  51
  52 .. code-block:: php
  53
  54    <?php
  55    # Translators: short for 'Number'
  56    i18n("No.");
  57
  58    # Translators: not 'Yes'
  59    i18n("No");
  60
  61 With the ``Translators:`` keyword in a comment directly in front of the line with the string to be translated such hints can be marked.
  62
  63 Generating the .pot file from source
  64 ------------------------------------
  65
  66 To generate a .pot file for translators on has to use the following command:
  67
  68 .. code-block:: bash
  69
  70   $ xgettext -f po/pofilelist.txt --keyword=i18n --keyword=translate \
  71    --add-comments=Translators
  72   $ sed -i 's.^"Content-Type: text/plain; charset=CHARSET\\n".\
  73   "Content-Type: text/plain; charset=UTF-8\\n".' messages.po
  74   $ mv messages.po messages.pot
  75
  76 This will generate a file named ``messages.pot``.
  77
  78 Accessing the Transifex files
  79 =============================
  80
  81 Transifex does not have direct repository integration anymore.
  82 They have created a command line client namend ``tx``::
  83
  84    $ tx init
  85    Creating .tx folder...
  86    Transifex instance [http://www.transifex.net]:
  87    Creating skeleton...
  88    Creating config file...
  89    Done.
  90    $ tx set --auto-remote http://www.transifex.net/projects/p/davical/
  91    Auto configuring local project from remote URL...
  92    Getting details for project davical
  93    1 resources found. Configuring...
  94    Configuring resource davical.messagespot.
  95    Done.
  96    $ tx pull -a
  97    Pulling translations for resource davical.messagespot (source: None)
  98    New translations found for the following languages: nl, et, fr, de, hu, it, ja, nb_NO, pl, ru, es_AR, sv
  99    Pulling translations for resource davical.messagespot (source: None)
 100     -> nl: translations/davical.messagespot/nl.po
 101     -> et: translations/davical.messagespot/et.po
 102     -> fr: translations/davical.messagespot/fr.po
 103     -> de: translations/davical.messagespot/de.po
 104     -> hu: translations/davical.messagespot/hu.po
 105     -> it: translations/davical.messagespot/it.po
 106     -> ja: translations/davical.messagespot/ja.po
 107     -> nb_NO: translations/davical.messagespot/nb_NO.po
 108     -> pl: translations/davical.messagespot/pl.po
 109     -> ru: translations/davical.messagespot/ru.po
 110     -> es_AR: translations/davical.messagespot/es_AR.po
 111     -> sv: translations/davical.messagespot/sv.po
 112    Done.
 113