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 Testing your changes without installing ELinks:
  78 ---------------------------------------------------
  79
  80 It is possible to test translation updates without installing ELinks. After
  81 building both ELinks and the po files, simply start ELinks from the top-level
  82 directory in the source tree using:
  83
  84         $ ./src/elinks
  85
  86 It will then load po files from the po/ directory in the source tree.
  87
  88 1.3 Making the new language file part of ELinks:
  89 ------------------------------------------------
  90
  91 Finally to make it part of the ELinks distribution send it to one of the
  92 mailinglists or file it as a bug at <http://bugzilla.elinks.cz>.
  93
  94
  95 2. Updating .po files:
  96 ======================
  97
  98 2.1 Tools needed:
  99 -----------------
 100
 101 There are a great deal of tools for editing and working with .po files most are
 102 described in the gettext manual availabe at <http://www.gnu.org/manual/gettext>
 103 or by typing `info gettext` on some systems. Some editors have special .po modes
 104 to help spot errors etc. but nothing fancy is required to update only some
 105 reasonable editor.
 106
 107 In order to compile, get warnings and actually use your updated language file
 108 you will however need the gettext tools. If you don't have any of these tools
 109 please don't hesitate to still do the update and send it to the mailinglist or
 110 bugzilla so it can be added to CVS. By next release or nightly generated tarball
 111 you can then make use of your updates.
 112
 113 2.2 The basics of updating:
 114 ---------------------------
 115
 116 2.2.1 Singular forms, general rules:
 117 ------------------------------------
 118
 119 Each string that needs to be translated will look like this:
 120
 121         #: src/dialogs/info.c:184
 122         #, fuzzy, c-format
 123         msgid "Cache content: %s"
 124         msgstr "Cacheindhold: %s"
 125
 126 Lines starting with '#' are comments or control hints for the po compiler.  The
 127 text following '#:' is a listing of each place (filename and line number) in the
 128 code where the string is used. Text following '#,' are a comma separated list of
 129 control hints:
 130
 131         'fuzzy'
 132
 133                 means that the string was changed in the code and the translator
 134                 needs to check if the translation is still ok. When it has been
 135                 checked or updated it is safe to remove 'fuzzy' and the
 136                 following comma.
 137
 138         'c-format'
 139
 140                 is a hint to the compiler, checker and translator that the
 141                 string uses printf format.
 142
 143 The string following 'msgid' are the original untranslated string. It is used to
 144 get the translated one so: DO NEVER CHANGE IT. If you spot an error in it change
 145 it in the code instead and resync your .po files using make update-po.
 146
 147 The string following 'msgstr' is the translated string.
 148 TODO: write about the meaning of % fragments.
 149
 150 Some strings contain '~' (tilde) chars. They are used to mark hotkeys in text
 151 for menu entries. The char following the '~' is the hotkey char. So in the
 152 string "Global ~history" the hotkey will become 'h'. You should try and keep
 153 hotkeys unique. If you configure ELinks with --enable-debug conflicting hotkeys
 154 will be visible.
 155
 156 Some translations may become obsolete due to code modifications, these will be
 157 marked by #~ prefix, and moved at end of file. Keeping them may be a good thing
 158 since a modification can be reversed later and then gettext tools will reuse
 159 these special lines at resync time. If, at some time, you think some of these
 160 lines will never be reused, feel free to delete them to reduce file size.
 161
 162 A special msgid ("") contains .po file headers, you may update them as
 163 well, especially Last-Translator and PO-Revision-Date fields.
 164
 165 2.2.2 Plurals forms:
 166 --------------------
 167
 168 First set Plural-Forms: header (msgid "" at top of .po file) to some correct
 169 value, depending on language.
 170
 171 To help you in this, here is an excerpt from GNU gettext documentation:
 172
 173 Only one form:
 174         Some languages only require one single form. There is no distinction
 175         between the singular and plural form. An appropriate header entry
 176         would look like this:
 177
 178         Plural-Forms: nplurals=1; plural=0;
 179
 180         Languages with this property include:
 181
 182         Finno-Ugric family
 183                 Hungarian
 184         Asian family
 185                 Japanese, Korean
 186         Turkic/Altaic family
 187                 Turkish
 188
 189 Two forms, singular used for one only:
 190         This is the form used in most existing programs since it is what English
 191         is using. A header entry would look like this:
 192
 193         Plural-Forms: nplurals=2; plural=n != 1;
 194
 195         (Note: this uses the feature of C expressions that boolean expressions
 196          have to value zero or one.)
 197
 198         Languages with this property include:
 199
 200         Germanic family
 201                 Danish, Dutch, English, German, Norwegian, Swedish
 202         Finno-Ugric family
 203                 Estonian, Finnish
 204         Latin/Greek family
 205                 Greek
 206         Semitic family
 207                 Hebrew
 208         Romanic family
 209                 Italian, Portuguese, Spanish
 210         Artificial
 211                 Esperanto
 212
 213 Two forms, singular used for zero and one:
 214         Exceptional case in the language family. The header entry would be:
 215
 216         Plural-Forms: nplurals=2; plural=n>1;
 217
 218         Languages with this property include:
 219
 220         Romanic family
 221                 French, Brazilian Portuguese
 222
 223 Three forms, special case for zero:
 224         The header entry would be:
 225
 226         Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
 227
 228         Languages with this property include:
 229
 230         Baltic family
 231                 Latvian
 232
 233 Three forms, special cases for one and two:
 234         The header entry would be:
 235
 236         Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
 237
 238         Languages with this property include:
 239
 240         Celtic
 241                 Gaeilge (Irish)
 242
 243 Three forms, special case for numbers ending in 1[2-9]:
 244         The header entry would look like this:
 245
 246         Plural-Forms: nplurals=3; \
 247                 plural=n%10==1 && n%100!=11 ? 0 : \
 248                 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
 249
 250         Languages with this property include:
 251
 252         Baltic family
 253                 Lithuanian
 254
 255 Three forms, special cases for numbers ending in 1 and 2, 3, 4,
 256 except those ending in 1[1-4]:
 257         The header entry would look like this:
 258
 259         Plural-Forms: nplurals=3; \
 260                 plural=n%10==1 && n%100!=11 ? 0 : \
 261                 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 262
 263         Languages with this property include:
 264
 265         Slavic family
 266                 Croatian, Czech, Russian, Slovak, Ukrainian
 267
 268 Three forms, special case for one and some numbers ending in 2, 3, or 4:
 269         The header entry would look like this:
 270
 271         Plural-Forms: nplurals=3; \
 272                 plural=n==1 ? 0 : \
 273                 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 274
 275         Languages with this property include:
 276
 277         Slavic family
 278                 Polish
 279
 280 Four forms, special case for one and all numbers ending in 02, 03, or 04:
 281         The header entry would look like this:
 282
 283         Plural-Forms: nplurals=4; \
 284                 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 285
 286         Languages with this property include:
 287
 288         Slavic family
 289                 Slovenian
 290
 291
 292 More info at http://www.gnu.org/software/gettext
 293
 294
 295 Plural forms will appear like this in .po file:
 296
 297 #: src/dialogs/info.c:259
 298 #, c-format
 299 msgid "%d session"
 300 msgid_plural "%d sessions"
 301 msgstr[0] "%d session"
 302 msgstr[1] "%d sessions"
 303
 304 msgid and msgid_plural should not be changed, each msgstr[n] line contains
 305 translation for each plural form.
 306
 307
 308 2.3 Synchronizing .po files with the code
 309 -----------------------------------------
 310
 311 IMPORTANT: if you changed strings in the code, or if you're using a cvs version
 312 of ELinks, take care of synchronization between code and po files.  Before any
 313 change to a po file, you must synchronize it with code.
 314
 315 To update only one file you may use:
 316
 317         cd po/ ; make update-po PO=<lang>.po
 318
 319 or
 320
 321         cd po/ ; make update-po PO=<lang>
 322
 323 where <lang> has to be replaced by ie. fr, de, da, cs...
 324
 325 If this fails or you want to update all .po files, use:
 326
 327         cd po/ ; make update-po
 328
 329 2.4 Checking updated .po files
 330 ------------------------------
 331
 332 After updating a .po file you should always check it for errors in the c-format
 333 fragments, etc. You can do this by running:
 334
 335         cd po/ ; make check-po PO=<lang>.po
 336
 337 or
 338
 339         cd po/ ; make check-po PO=<lang>
 340
 341 It can potentially report some false positives if the .po file contains fuzzy
 342 message strings.
 343
 344 2.5 Making the updates part of ELinks:
 345 --------------------------------------
 346
 347 If the language file is already added finally run make to compile and check the
 348 language file for errors and fix any warnings you get. Then patch your changes
 349 and send it to one of the mailinglists or file it as a bug at
 350 <http://bugzilla.elinks.cz>.
 351
 352
 353 3. Statistics:
 354 ==============
 355
 356 Some people (like Zas but other mortals as well ;) like to know how much of the
 357 language file is up-to-date. This can be accomplished by running the
 358 gen_translations_stats.sh script from the po/ directory. It will list the
 359 current status of each language file. Be proud if your language file rank higher
 360 or the same as the French one.
 361
 362
 363 vim: textwidth=80