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