doc/translation-help.txt

   1 Pacman - Translating
   2 ====================
   3
   4 This document is here to guide you in helping translate pacman messages,
   5 libalpm messages, and the manpages for the entire pacman package.
   6
   7 We are currently using http://www.transifex.net/[Transifex] as the translation
   8 platform for pacman and libalpm. You will need to sign up for an account there
   9 and then register with a translation team on the
  10 http://www.transifex.net/projects/p/archlinux-pacman/[pacman project page].
  11
  12 NOTE: This may be old information due to our switch to Transifex, but the
  13 gettext website is a very useful guide to read before embarking on translation
  14 work, as it describes many of the commands in more detail than I will here:
  15 http://www.gnu.org/software/gettext/manual/html_node/gettext.html[].  In
  16 addition, this site presents a small tutorial that I found useful:
  17 http://oriya.sarovar.org/docs/gettext/[].
  18
  19
  20 Translating Messages
  21 --------------------
  22
  23 Overview
  24 ~~~~~~~~
  25
  26 There are two separate message catalogs in pacman- one for the backend
  27 (libalpm) and one for the frontend (pacman and scripts). These correspond to
  28 the `lib/libalpm/po` and `po` directories in the pacman source, respectively.
  29
  30 Translation message files are a specially formatted text file containing the
  31 original message and the corresponding translation. These po files can then
  32 either be hand edited, or modified with a tool such as poedit, gtranslator or
  33 kbabel. Using a translation tool tends to make the job easier.
  34
  35 Please read up on Transifex usage using the
  36 http://help.transifex.net/[Transifex Help] if you are not familiar.
  37
  38 Here is an example set of commands if you have a source code checkout and are
  39 not worried about any local translations being overwritten. The .tx/ directory
  40 is checked into the git repository so is preconfigured with the two project
  41 resources (See `tx status` output for a quick overview).
  42
  43     tx pull -f
  44     poedit po/<mylang>.po
  45     poedit lib/libalpm/po/<mylang>.po
  46     tx push -t -l <mylang>
  47
  48 Or to just push one of the two available resources:
  49
  50     tx push -r archlinux-pacman.pacman-pot -t -l fi
  51     tx push -r archlinux-pacman.libalpm-pot -t -l fi
  52
  53 See the <<Notes,Notes>> section for additional hints on translating.
  54
  55 Pre-release Updates
  56 ~~~~~~~~~~~~~~~~~~~
  57
  58 A week or two before each release, the codebase will go into a string freeze
  59 and an email will be sent to the mailto:pacman-dev@archlinux.org[pacman-dev]
  60 mailing list asking for translations. This email will have a prefix of
  61 *[translation]* for anyone looking to set up an email filter.
  62
  63 At this time, the latest `.po` language files will be made available at the
  64 Transifex project page.  Each language will have two files available (backend
  65 and frontend). Translators interested in helping are encouraged to use the
  66 features of Transifex to let others know they are currently translating their
  67 language.
  68
  69 Once a translator has completed the translation (*OR* realizes they do not have
  70 time to finish), please upload your progress back to the Transifex site.
  71
  72 NOTE: Please upload your translations as soon as possible- this will give other
  73 speakers of your language time to review your translations and update them as
  74 necessary.
  75
  76 Incremental Updates
  77 ~~~~~~~~~~~~~~~~~~~
  78
  79 If you have more advanced needs you will have to get a copy of the pacman
  80 repository.
  81
  82     git clone git://projects.archlinux.org/pacman.git pacman
  83
  84 Next, you will need to run `./autogen.sh` and `./configure` in the base
  85 directory to generate the correct Makefiles. At this point, all necessary
  86 make targets will be generated and we can begin updating the translation
  87 files.
  88
  89 We need to first update the main message catalog file. Navigate into either the
  90 `lib/libalpm/po` or `po` directory depending on which translation you wish to
  91 work on first, and execute the following command.  If you are working in the
  92 `po/` tree, replace 'libalpm.pot' with 'pacman.pot':
  93
  94     make libalpm.pot-update
  95
  96 Next, update your specific language's translation file:
  97
  98     make <po file>-update
  99
 100 At this point, you can do the translation. To submit your changes, either email
 101 the new `.po` file to the mailing-list with *[translation]* in the subject, or
 102 submit a GIT-formatted patch (please do not include any `.pot` file changes).
 103
 104 As a shortcut, all translation files (including `.pot` files) can be updated
 105 with the following command:
 106
 107     make update-po
 108
 109 Adding a New Language
 110 ~~~~~~~~~~~~~~~~~~~~~
 111
 112 Making a new language is not too hard, but be sure to follow all the steps.
 113 You will have to do the following steps in both the `lib/libalpm/po/` and `po/`
 114 directories, substituting where appropriate. First, edit the `LINGUAS` file and
 115 add your new language code at the bottom. Next, run the following command,
 116 substituting 'libalpm.pot' or 'pacman.pot' for potfile depending on which
 117 directory you are currently working in:
 118
 119         msginit -l <lang code> -o <lang code>.po -i <potfile>
 120
 121 You can then also add your language code to the end of the `LINGUAS` file
 122 located in each po directory.
 123
 124 Look at the current message files for more guidance if necessary. Once you
 125 create the new language file, you may need to slightly modify the headers;
 126 try to make them look similar to the other .po file headers. In addition, for
 127 all new translations we would strongly recommend using UTF-8 encoding.
 128
 129 Notes[[Notes]]
 130 ~~~~~~~~~~~~~~
 131
 132 msgid and msgstr 'variables' can be on as many lines as necessary. Line breaks
 133 are ignored- if you need a literal line break, use an `\n` in your string. The
 134 following two translations are equivalent:
 135
 136     msgstr "This is a test translation"
 137
 138     msgstr ""
 139     "This is a test translation"
 140
 141 If you want to test the translation (for example, the frontend one):
 142
 143     rm *.gmo stamp-po
 144     make
 145     cp <lang code>.gmo /usr/share/locale/<lang code>/LC_MESSAGES/pacman.mo
 146
 147
 148 Translating Manpages
 149 --------------------
 150
 151 There are currently no efforts underway to include translated manpages in the
 152 pacman codebase. However, this is not to say translations are unwelcome. If
 153 someone has experience with i18n manpages and how to best include them with our
 154 source, please contact the pacman-dev mailing list at
 155 mailto:pacman-dev@archlinux.org[].
 156
 157 Some community efforts have been made to translate manpages, and these can be
 158 found in the link:http://aur.archlinux.org[AUR] (Arch User Repository). Please
 159 check there first before undergoing a translation effort to ensure you are not
 160 duplicating efforts.
 161
 162 /////
 163 vim: set ts=2 sw=2 syntax=asciidoc et:
 164 /////