doc/HOWTO.translating_abook

   1 Foreword
   2 --------
   3
   4 This howto is deliberately incomplete, focusing on working with gettext
   5 for abook specifically. For more comprehensive informations or to grasp
   6 the Big Picture of Native Language Support, you should refer to the GNU
   7 gettext manual at: http://www.gnu.org/software/gettext/manual/
   8
   9 After a quick description of how things work, three parts aimed at three
  10 different people involved in the translation chain will follow: coders,
  11 language coordinator, and translators.
  12
  13
  14 Overview
  15 --------
  16
  17 To be able to display texts in the native language of the user, two
  18 steps are required: internationalization (i18n) and localization (l10n).
  19
  20 i18n is about making abook support multiple languages. It is performed
  21 by coders, who will mark translatable texts and provide a way to display
  22 them translated at runtime.
  23
  24 l10n is about making the i18n'ed abook adapt to the specific language of
  25 the user, ie translating the strings previously marked by the
  26 developers, and setting the environment correctly for abook to use the
  27 result of this translation.
  28
  29 So, translatable strings are first marked by the coders within the C
  30 source files, then gathered in a template file (abook.pot). The content
  31 of this template file is then merged with the translation files for each
  32 language (fr.po for french, for instance). A given translation team will
  33 take this file, translate its strings, and send it back to the
  34 developers. At compilation time, a binary version of this file (for
  35 efficiency reasons) will be produced (fr.mo), and then installed.  Then
  36 abook will use this file at runtime, translating the strings according
  37 to the locale settings of the user.
  38
  39
  40 The coders
  41 ----------
  42
  43 * Translating a new file.
  44   First, you have to make your C source file aware of the gettext
  45   macros by including "gettext.h".
  46   Then, you need to make gettext aware that this file contains
  47   translatable strings by adding its name to po/POTFILES.in
  48
  49 * Translatable strings
  50   This is a two parts process: marking the string to tell gettext to
  51   make it available to translators (via the .pot file), and actually
  52   translating the string at runtime.
  53   There is basically three functions/macros available:
  54    * _(): mark the string and translate it.
  55    * N_(): only mark the string
  56    * gettext(): only translate
  57   The last two are used in conjunction, when the string declaration is
  58   dissociated in the code from its actual use. You'll then use N_() to
  59   mark the string, and later use a gettext() call to translate it.
  60
  61 And that's all, really.
  62
  63 Should the need arise later, it might be handy to know that a few more
  64 mechanisms exist, for example to deal with ambiguities (same string but
  65 with different roles should be translated differently), or plurals, etc.
  66 This is all explained in depth in the gettext manual. But the three
  67 macros seen above should be enough to handle about all the situations
  68 met while internationalizing abook.
  69
  70
  71 The language coordinator
  72 ------------------------
  73
  74 This is neither a coder, nor a translator. His role is in-between. He
  75 is the one who will merge the strings changed by the coders into the
  76 translation files, and merge back the translation files sent to him by
  77 the translators. He will also take care of initiating language files
  78 whenever a new translator shows up.
  79
  80 * Updating the template file
  81   Translatable strings evolve all the time: coders add some, remove
  82   others, change a lot of them. At some point, these strings need to be
  83   merged into the po/abook.pot file to reflect the current situation.
  84   This is done simply by executing 'make -C po abook.pot-update'.
  85
  86   The xgettext utility will then parse the files listed into
  87   po/POTFILES.in, looking for marked strings, and updating po/abook.pot.
  88
  89 * Merging the new strings into the po-files
  90   After updating, you will have to merge the changes into every .po
  91   file. This is done by running 'make -C po update-po', which will use
  92   the msgmerge program to perform this task.
  93
  94   Then, some strings will be marked as "fuzzy" (ie needing review,
  95   because of slight changes), some strings will be commented out
  96   because of removal from sources, some strings will be added, and
  97   some strings will not be changed at all. The po-file is now in sync.
  98
  99 * Compiling plain text translation into binary files suited for runtime
 100   Please note that this is implicitly done in the previous step.
 101   Anyway, you just have to run 'make -C po update-gmo' to update the
 102   mo-files (or gmo-files, which is a GNU specific naming) from the
 103   po-files.
 104
 105   For (re)generating just one particular language (french as example),
 106   use 'cd po ; msgfmt -c --statistics -o fr.gmo fr.po'.
 107
 108 * Initiating the translation of a new language
 109   So a Swedish translator just contacted you to contribute a
 110   translation. Nice!
 111
 112   First, find out what the locale name is. For swedish, it is 'sv_SE',
 113   or simply 'sv'. This is the value the user will have to put in his
 114   LC_MESSAGES/LANG environment variable for software to be translated.
 115
 116   Then, go into the po/directory, and create a new po-file from the
 117   template file: 'msginit -i abook.pot -o sv.po -l sv --no-translator'.
 118   Now, having this sv.po file, the translator is ready to begin.
 119
 120   Last step is making gettext aware of this new language. Just add the
 121   locale name to the po/LINGUAS file.
 122
 123 * Committing a po-file received from a translator
 124   The Swedish translator just sent you an updated translation, in
 125   sv.po.new. Before replacing sv.po in the po/ directory and committing
 126   it to cvs, you should check everything is fine, with this step:
 127   'msgmerge sv.po.new abook.pot -o sv.po'.
 128
 129
 130 The translators
 131 ---------------
 132
 133 The gettext part is the easy one: the format of the po-files is really
 134 straightforward. The hard part will be the quest for the right word, the
 135 best fitting formulation.
 136
 137 po-files are made of four things:
 138  * location lines: tells you where the strings can be seen (name of file
 139    and line number), in case you need to see a bit of context.
 140  * msgid lines: the strings to translate.
 141  * msgstr lines: the translated strings.
 142  * lines prefixed with '#': comments (some with a special meaning, as we
 143    will see below).
 144
 145 Basically, all you have to do is fill the msgstr lines with the
 146 translation of the above msgid line. And send the result to the language
 147 coordinator of abook.
 148
 149 A few notes:
 150
 151 * Fuzzy strings
 152   You will meet strings marked with a "#, fuzzy" comment. abook won't
 153   use the translations of such strings until you do something about
 154   them.
 155
 156   A string being fuzzy means either that the string has already been
 157   translated but has since been changed in the sources of the program,
 158   or that this is a new string for which gettext made a 'wild guess' for
 159   the translation, based on other strings in the file.
 160
 161   It means you have to review the translation. Sometimes, the original
 162   string has changed just because a typo has been fixed. In this case,
 163   you won't have to change anything. But sometimes, the translation will
 164   no longer be accurate and needs to be changed.
 165
 166   Once you are done and happy with the translation, just remove the
 167   "#, fuzzy" line, and the translation will be used again in abook.
 168
 169 * c-format strings and special sequences
 170   Some strings have the following comment: "#, c-format".
 171   This tells that parts of the string to translate have a special
 172   meaning for the program, and that you should leave them alone.
 173
 174   For instance, %-sequences, like "%s". These means that abook will
 175   replace them with another string. So it is important it remains.
 176
 177   There are also \-sequences, like \n or \t. Leave them, too. The former
 178   represents an end of line, the latter a tabulation.
 179
 180 * Translations can be wrapped
 181   If lines are too long, you can just break them like this:
 182     msgid ""
 183     "some very long line"
 184     "another line"
 185
 186 * po-file header
 187   At the very beginning of the po-file, the first string form a header,
 188   where various kind of information has to be filled in. Most important
 189   one is the charset. It should resemble
 190   "Content-Type: text/plain; charset=utf-8\n"
 191
 192   You should also fill in the Last-Translator field, so that potential
 193   contributors can contact you if they want to join you in the
 194   translation team, or have remarks/typo fixes to give about the
 195   translations. You can either just give your name/nick, or add an email
 196   address, f ex "Last-Translator: Cédric Duval <cedricduval+abook@free.fr>\n".
 197
 198 * Comments
 199   Adding comments (lines begining with the '#' character) can be a good
 200   way to point out problems or translation difficulties to proofreaders
 201   or other members of your team.
 202
 203 * Strings size
 204   abook is a curses/console program, thus it can be heavily dependant on
 205   the terminal size (number of columns). You should think about this
 206   when translating. Often, a string must fit into a single line
 207   (standard length is 80 characters). Don't translate blindly, try to
 208   look where your string will be displayed to adapt your translation.
 209
 210 * A few useful tools
 211   The po-file format is very simple, and the file can be edited with a
 212   standard text editor.
 213
 214   But if you prefer, there are few specialized tools you may find
 215   convenient for translating:
 216    * poEdit (http://www.poedit.org/)
 217    * KBabel (http://i18n.kde.org/tools/kbabel/)
 218    * GTranslator (http://gtranslator.sourceforge.net/)
 219    * Emacs po mode
 220    * Vim po mode
 221      (http://vim.sourceforge.net/scripts/script.php?script_id=695
 222      or http://vim.sourceforge.net/scripts/script.php?script_id=913)
 223    * And certainly others I'm not aware of. Just tell me!
 224
 225
 226 And finally
 227 -----------
 228
 229 I hope you'll have fun contributing to a more internationalized world. :)
 230
 231 If you have any more questions, don't hesitate to contact me
 232 (Cédric Duval <cedricduval+abook@free.fr>) or the abook development
 233 mailing list (http://lists.sourceforge.net/lists/listinfo/abook-devel).
 234