po/README

   1                         Guide for Translators
   2
   3 1. Adding a new language:
   4 =========================
   5
   6 Assuming you have downloaded the distributed source tarball, unpacked it and
   7 changed directory to the root directory of the unpacked source tarball first
   8 make the po template file:
   9
  10         $ cd po/
  11         $ make elinks.pot
  12
  13 Use the elinks.pot template file as the basis for you translation:
  14
  15         $ cp elinks.pot <your language code>.po
  16
  17 Modify .po file header that should look like this:
  18
  19 # SOME DESCRIPTIVE TITLE.
  20 # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
  21 # This file is distributed under the same license as the PACKAGE package.
  22 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
  23 #
  24 #, fuzzy
  25 msgid ""
  26 msgstr ""
  27 "Project-Id-Version: PACKAGE VERSION\n"
  28 "POT-Creation-Date: 2005-03-03 11:22+0100\n"
  29 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
  30 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
  31 "Language-Team: LANGUAGE <LL@li.org>\n"
  32 "MIME-Version: 1.0\n"
  33 "Content-Type: text/plain; charset=CHARSET\n"
  34 "Content-Transfer-Encoding: 8bit\n"
  35 "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
  36
  37 Once done don't forget to remove '#, fuzzy' line.
  38 Then follow the instructions in the 'Updating .po files' section below.
  39
  40 1.1 Integrating a new language file:
  41 ------------------------------------
  42
  43 When you are done editing the .po file you need to integrate it as part of
  44 ELinks. If you don't feel comfortable editing the ELinks C-language source code
  45 don't hesitate to get a developer to do it for you.
  46
  47 First change directory to the root directory of the unpacked source tarball:
  48
  49         $ cd ../
  50
  51 Add your language code to the ALL_LINGUAS string in configure.in (keep the
  52 alphabetic order ;). To make the change take effect you have to rebuild all
  53 Makefiles:
  54
  55         $ ./autogen.sh
  56         $ ./configure
  57
  58 The language file will now be compiled when you run make and you can check the
  59 translation file for errors and fix any warnings you get.
  60
  61 Next thing is to add it to the Setup->Language menu. This is done by adding an
  62 entry in the language array in src/intl/gettext/libintl.c, and should not
  63 require any C coding skills, just copy an already existing entry and edit the
  64 name of your language (in English) so you end up with something like:
  65
  66         struct language languages[] = {
  67                 {"System", "system"},
  68                 {"English", "en"},
  69
  70                 ... other entries ...
  71                 {"<name for your language in English>", "<your language code>"},
  72                 ... other entries ...
  73
  74                 {NULL, NULL},
  75         };
  76
  77 1.2 Making the new language file part of ELinks:
  78 ------------------------------------------------
  79
  80 Finally to make it part of the ELinks distribution send it to one of the
  81 mailinglists or file it as a bug at <http://bugzilla.elinks.or.cz>.
  82
  83
  84 2. Updating .po files:
  85 ======================
  86
  87 2.1 Tools needed:
  88 -----------------
  89
  90 There are a great deal of tools for editing and working with .po files most are
  91 described in the gettext manual availabe at <http://www.gnu.org/manual/gettext>
  92 or by typing `info gettext` on some systems. Some editors have special .po modes
  93 to help spot errors etc. but nothing fancy is required to update only some
  94 reasonable editor.
  95
  96 In order to compile, get warnings and actually use your updated language file
  97 you will however need the gettext tools. If you don't have any of these tools
  98 please don't hesitate to still do the update and send it to the mailinglist or
  99 bugzilla so it can be added to CVS. By next release or nightly generated tarball
 100 you can then make use of your updates.
 101
 102 2.2 The basics of updating:
 103 ---------------------------
 104
 105 2.2.1 Singular forms, general rules:
 106 ------------------------------------
 107
 108 Each string that needs to be translated will look like this:
 109
 110         #: src/dialogs/info.c:184
 111         #, fuzzy, c-format
 112         msgid "Cache content: %s"
 113         msgstr "Cacheindhold: %s"
 114
 115 Lines starting with '#' are comments or control hints for the po compiler.  The
 116 text following '#:' is a listing of each place (filename and line number) in the
 117 code where the string is used. Text following '#,' are a comma separated list of
 118 control hints:
 119
 120         'fuzzy'
 121
 122                 means that the string was changed in the code and the translator
 123                 needs to check if the translation is still ok. When it has been
 124                 checked or updated it is safe to remove 'fuzzy' and the
 125                 following comma.
 126
 127         'c-format'
 128
 129                 is a hint to the compiler, checker and translator that the
 130                 string uses printf format.
 131
 132 The string following 'msgid' are the original untranslated string. It is used to
 133 get the translated one so: DO NEVER CHANGE IT. If you spot an error in it change
 134 it in the code instead and resync your .po files using make update-po.
 135
 136 The string following 'msgstr' is the translated string.
 137 TODO: write about the meaning of % fragments.
 138
 139 Some strings contain '~' (tilde) chars. They are used to mark hotkeys in text
 140 for menu entries. The char following the '~' is the hotkey char. So in the
 141 string "Global ~history" the hotkey will become 'h'. You should try and keep
 142 hotkeys unique. If you configure ELinks with --enable-debug conflicting hotkeys
 143 will be visible.
 144
 145 Some translations may become obsolete due to code modifications, these will be
 146 marked by #~ prefix, and moved at end of file. Keeping them may be a good thing
 147 since a modification can be reversed later and then gettext tools will reuse
 148 these special lines at resync time. If, at some time, you think some of these
 149 lines will never be reused, feel free to delete them to reduce file size.
 150
 151 A special msgid ("") contains .po file headers, you may update them as
 152 well, especially Last-Translator and PO-Revision-Date fields.
 153
 154 2.2.2 Plurals forms:
 155 --------------------
 156
 157 First set Plural-Forms: header (msgid "" at top of .po file) to some correct
 158 value, depending on language.
 159
 160 To help you in this, here is an excerpt from GNU gettext documentation:
 161
 162 Only one form:
 163         Some languages only require one single form. There is no distinction
 164         between the singular and plural form. An appropriate header entry
 165         would look like this:
 166
 167         Plural-Forms: nplurals=1; plural=0;
 168
 169         Languages with this property include:
 170
 171         Finno-Ugric family
 172                 Hungarian
 173         Asian family
 174                 Japanese, Korean
 175         Turkic/Altaic family
 176                 Turkish
 177
 178 Two forms, singular used for one only:
 179         This is the form used in most existing programs since it is what English
 180         is using. A header entry would look like this:
 181
 182         Plural-Forms: nplurals=2; plural=n != 1;
 183
 184         (Note: this uses the feature of C expressions that boolean expressions
 185          have to value zero or one.)
 186
 187         Languages with this property include:
 188
 189         Germanic family
 190                 Danish, Dutch, English, German, Norwegian, Swedish
 191         Finno-Ugric family
 192                 Estonian, Finnish
 193         Latin/Greek family
 194                 Greek
 195         Semitic family
 196                 Hebrew
 197         Romanic family
 198                 Italian, Portuguese, Spanish
 199         Artificial
 200                 Esperanto
 201
 202 Two forms, singular used for zero and one:
 203         Exceptional case in the language family. The header entry would be:
 204
 205         Plural-Forms: nplurals=2; plural=n>1;
 206
 207         Languages with this property include:
 208
 209         Romanic family
 210                 French, Brazilian Portuguese
 211
 212 Three forms, special case for zero:
 213         The header entry would be:
 214
 215         Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
 216
 217         Languages with this property include:
 218
 219         Baltic family
 220                 Latvian
 221
 222 Three forms, special cases for one and two:
 223         The header entry would be:
 224
 225         Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
 226
 227         Languages with this property include:
 228
 229         Celtic
 230                 Gaeilge (Irish)
 231
 232 Three forms, special case for numbers ending in 1[2-9]:
 233         The header entry would look like this:
 234
 235         Plural-Forms: nplurals=3; \
 236                 plural=n%10==1 && n%100!=11 ? 0 : \
 237                 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
 238
 239         Languages with this property include:
 240
 241         Baltic family
 242                 Lithuanian
 243
 244 Three forms, special cases for numbers ending in 1 and 2, 3, 4,
 245 except those ending in 1[1-4]:
 246         The header entry would look like this:
 247
 248         Plural-Forms: nplurals=3; \
 249                 plural=n%10==1 && n%100!=11 ? 0 : \
 250                 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 251
 252         Languages with this property include:
 253
 254         Slavic family
 255                 Croatian, Czech, Russian, Slovak, Ukrainian
 256
 257 Three forms, special case for one and some numbers ending in 2, 3, or 4:
 258         The header entry would look like this:
 259
 260         Plural-Forms: nplurals=3; \
 261                 plural=n==1 ? 0 : \
 262                 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 263
 264         Languages with this property include:
 265
 266         Slavic family
 267                 Polish
 268
 269 Four forms, special case for one and all numbers ending in 02, 03, or 04:
 270         The header entry would look like this:
 271
 272         Plural-Forms: nplurals=4; \
 273                 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 274
 275         Languages with this property include:
 276
 277         Slavic family
 278                 Slovenian
 279
 280
 281 More info at http://www.gnu.org/software/gettext
 282
 283
 284 Plural forms will appear like this in .po file:
 285
 286 #: src/dialogs/info.c:259
 287 #, c-format
 288 msgid "%d session"
 289 msgid_plural "%d sessions"
 290 msgstr[0] "%d session"
 291 msgstr[1] "%d sessions"
 292
 293 msgid and msgid_plural should not be changed, each msgstr[n] line contains
 294 translation for each plural form.
 295
 296
 297 2.3 Synchronizing .po files with the code
 298 -----------------------------------------
 299
 300 IMPORTANT: if you changed strings in the code, or if you're using a cvs version
 301 of ELinks, take care of synchronization between code and po files.  Before any
 302 change to a po file, you must synchronize it with code.
 303
 304 To update only one file you may use:
 305
 306         cd po/ ; make update-po PO=<lang>.po
 307
 308 or
 309
 310         cd po/ ; make update-po PO=<lang>
 311
 312 where <lang> has to be replaced by ie. fr, de, da, cs...
 313
 314 If this fails or you want to update all .po files, use:
 315
 316         cd po/ ; make update-po
 317
 318 2.4 Checking updated .po files
 319 ------------------------------
 320
 321 After updating a .po file you should always check it for errors in the c-format
 322 fragments, etc. You can do this by running:
 323
 324         cd po/ ; make check-po PO=<lang>.po
 325
 326 or
 327
 328         cd po/ ; make check-po PO=<lang>
 329
 330 It can potentially report some false positives if the .po file contains fuzzy
 331 message strings.
 332
 333 2.5 Making the updates part of ELinks:
 334 --------------------------------------
 335
 336 If the language file is already added finally run make to compile and check the
 337 language file for errors and fix any warnings you get. Then patch your changes
 338 and send it to one of the mailinglists or file it as a bug at
 339 <http://bugzilla.elinks.or.cz>.
 340
 341
 342 3. Statistics:
 343 ==============
 344
 345 Some people (like Zas but other mortals as well ;) like to know how much of the
 346 language file is up-to-date. This can be accomplished by running the
 347 gen_translations_stats.sh script from the po/ directory. It will list the
 348 current status of each language file. Be proud if your language file rank higher
 349 or the same as the French one.
 350
 351
 352 $Id: README,v 1.9 2005/03/03 10:48:00 zas Exp $
 353 vim: textwidth=80