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 Git. 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. See GNU gettext documentation for details, at
 170 http://www.gnu.org/software/gettext
 171
 172 Plural forms will appear like this in .po file:
 173
 174 #: src/dialogs/info.c:259
 175 #, c-format
 176 msgid "%d session"
 177 msgid_plural "%d sessions"
 178 msgstr[0] "%d session"
 179 msgstr[1] "%d sessions"
 180
 181 msgid and msgid_plural should not be changed, each msgstr[n] line contains
 182 translation for each plural form.
 183
 184
 185 2.3 Synchronizing .po files with the code
 186 -----------------------------------------
 187
 188 IMPORTANT: if you changed strings in the code, or if you're using a Git version
 189 of ELinks, take care of synchronization between code and po files.  Before any
 190 change to a po file, you must synchronize it with code.
 191
 192 To update only one file you may use:
 193
 194         cd po/ ; make update-po PO=<lang>.po
 195
 196 or
 197
 198         cd po/ ; make update-po PO=<lang>
 199
 200 where <lang> has to be replaced by ie. fr, de, da, cs...
 201
 202 If this fails or you want to update all .po files, use:
 203
 204         cd po/ ; make update-po
 205
 206 2.4 Checking updated .po files
 207 ------------------------------
 208
 209 After updating a .po file you should always check it for errors in the c-format
 210 fragments, etc. You can do this by running:
 211
 212         cd po/ ; make check-po PO=<lang>.po
 213
 214 or
 215
 216         cd po/ ; make check-po PO=<lang>
 217
 218 It can potentially report some false positives if the .po file contains fuzzy
 219 message strings.
 220
 221 Note: It will in some situations report a false-positive. The only currently
 222 known issue is when the msgid contains a tilde not being used a an accelerator
 223 mark (e.g. "~/.elinks") and the translated msgstr do not.
 224
 225 2.5 Making the updates part of ELinks:
 226 --------------------------------------
 227
 228 If the language file is already added finally run make to compile and check the
 229 language file for errors and fix any warnings you get. Then patch your changes
 230 and send it to one of the mailinglists or file it as a bug at
 231 <http://bugzilla.elinks.cz>.
 232
 233
 234 3. Statistics:
 235 ==============
 236
 237 Some people (like Zas but other mortals as well ;) like to know how much of the
 238 language file is up-to-date. This can be accomplished by running the
 239 gen_translations_stats.sh script from the po/ directory. It will list the
 240 current status of each language file. Be proud if your language file rank higher
 241 or the same as the French one.
 242
 243
 244 vim: textwidth=80