README-I18N.en

   1 Mailman - The GNU Mailing List Management System
   2 Copyright (C) 2001-2003 by the Free Software Foundation, Inc.
   3 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
   4
   5
   6 INTERNATIONALIZATION
   7
   8     Mailman 2.1 is multilingual.  By default it supports English, but
   9     additional languages may also be available.  If the language you
  10     want to add is already supported by Mailman, then getting all your
  11     lists to also support that language is fairly easy.  You just need
  12     to go to the administrative web pages, click on the "Languages"
  13     category, and select the languages you want your list to support.
  14
  15     If the language you want to use has not been previously
  16     translated, or you don't know where to find the language pack for
  17     your language, read the section below or contact the Mailman
  18     internationalization mailing list mailman-i18n@python.org.
  19
  20
  21 ADDING NEW TRANSLATIONS
  22
  23     Suppose you want to add new translations for a previously
  24     unsupported language, what steps would you need to take?
  25
  26     First, you should send a message to mailman-i18n@python.org to
  27     make sure nobody has already created the translations for your
  28     language.  In the example below, we're going to create a
  29     translation for the mythical language "Fredonia" which has the
  30     official language code of "xx".
  31
  32     You should see
  33
  34         http://www.list.org/i18n.html
  35
  36     for more information on internationalizing Mailman.  Also, Simone
  37     Piunno -- who is the Italian translation champion -- has written
  38     up some nice instructions, which are provided below.
  39
  40     In general you need to do two things to add translations for a
  41     language in Mailman.  You need to translate the message catalog
  42     and you need to translate the templates.
  43
  44     To translate the message catalog, grab the file
  45     messages/mailman.pot and make a copy called mailman.po in the
  46     subdirectory messages/xx/LC_MESSAGES.  Then you edit the file and
  47     add the translations for each message identified in the catalog.
  48     It will be very helpful to have a good tool, such as KDE's KBabel
  49     tool, or po-mode for Emacs, for this part of the job.
  50
  51     Once you've added your translations, you can then run msgfmt over
  52     your .po file to generate messages/xx/LC_MESSAGE/mailman.mo.  Run
  53     "make" in the messages subdirectory to do this.
  54
  55     Next, create the subdirectory templates/xx and translate each of
  56     the files in templates/en/*.{html,txt}.  These you should also
  57     donate back to the Mailman project.
  58
  59     To make Mailman and your lists aware of the new language, follow
  60     the directions in the section above.
  61
  62
  63 TRANSLATION HINTS
  64
  65     Q: If your language uses non-ASCII characters, such as the cedilla in
  66        French, how should you add these to the catalogs and templates?
  67
  68     A: For any message that is destined for the web interface, use an
  69        HTML entity reference where appropriate.  For messages destined
  70        for email, you should use the non-ASCII characters explicitly.
  71        This includes both for the message catalog and the templates.
  72
  73
  74 RESYNCHRONIZING THE CATALOG
  75
  76     As Mailman development continues, new updated catalogs
  77     (i.e. mailman.pot files) will be made available.  As mailman.pot
  78     changes, the individual language catalogs
  79     (i.e. xx/LC_MESSAGES/mailman.po files) need to be updated as well.
  80
  81     In general, I as the Mailman maintainer will merge the new
  82     catalogs with the individual language catalogs, and commit the
  83     updates to CVS.  Translators should grab the new mailman.po files
  84     from CVS and update the translated messages.  They should also
  85     update the template translations.
  86
  87     For best results, you will probably want to keep current on
  88     changes to Mailman 2.1 in the CVS.  As Mailman 2.1 moves towards
  89     final release, the catalogs and templates should start to
  90     stabilize.  Alternatively, occasionally I will make new English
  91     language packs available on SourceForge, and you can use these to
  92     create your translations.
  93
  94
  95 DONATING YOUR TRANSLATION BACK TO MAILMAN
  96
  97     We'd really appreciate it if you donate your translations back to
  98     the Mailman project, so that others can benefit from your effort.
  99     You'll get credit of course, in the Mailman documentation.  Here
 100     are the steps to donate your translations, either the first time
 101     or subsequent updates.
 102
 103     The best thing to do is to send me <barry@python.org> a "tarball",
 104     i.e. a gzip'd tarfile, that can be unpacked in the top level
 105     directory of the Mailman CVS tree.  This would be the directory
 106     containing this README-I18N.en file.
 107
 108     Your tarball should contain two directories, where your donated
 109     language is `xx':
 110
 111         templates/xx
 112         messages/xx
 113
 114     In templates/xx there should be the translated templates, all the
 115     .txt and .html files, for your language, mirroring those in the
 116     English template directory (always the master copy).
 117
 118     In messages/xx you should have a single directory LC_MESSAGES, and
 119     in that directory a file called mailman.po, which is the human
 120     readable catalog for your language.  Do not send me the mailman.mo
 121     file, since I'll recreate it on my end, and that'll save on the
 122     size of the tarball.
 123
 124     That's basically it.  If you need to include a README, please call
 125     it README.xx and put it in the messages/xx directory.  README.xx
 126     can be in your native language.
 127
 128     You can email the tarball to me, and if this is the first
 129     installation of the language, please tell me what the
 130     add_language() call in Defaults.py.in should be for your
 131     language.
 132
 133
 134 CURRENT LIST OF LANGUAGE SUPPORTED OUT-OF-THE BOX
 135
 136     See http://www.list.org/i18n.html
 137
 138
 139 MORE INSTRUCTIONS
 140
 141     Here is the recipe that Simone Piunno used for the Italian
 142     translations:
 143
 144     "You can start without much technical knowledge, but if you want
 145     to keep your translation up-to-date (while the development branch
 146     evolves into the next stable release) you'd better learn how to
 147     use cvs and diff.
 148
 149     Here is my recipe.
 150
 151     Basically, you'll start by copying templates/en/* to your sandbox dir
 152     and then translating each file.  Keep in mind that %(foo)s is a
 153     variable reference (much like %s in C) and must be left untouched.
 154     Also, you must be able to recognize a markup tag (eg, <foo>) because
 155     they must be left untouched too, and you should know how to escape
 156     non-ASCII characters, e.g. "è" -> "&egrave;", but only in html files.
 157     Remember that if you need a literal % sign, it must be doubled: %%
 158
 159     Next, you copy messages/mailman.pot, renaming it to serbian.po.
 160     You can open this file with kbabel (a tool included in KDE SDK) and
 161     translate each string (original on the higher half of the window, your
 162     translation on the bottom half).
 163
 164     If you are a masochist, you can even use emacs PO mode ;)
 165     Keep attention to the same markers and escaping as above, with the added
 166     complexity that here it's harder to say when a string is html (e.g. used
 167     for web UI) or pure text (e.g used for email interface)
 168
 169     Then you try to compile you .po file:
 170
 171         msgfmt -v -o serbian.mo serbian.po
 172
 173     No error messages should appear.
 174
 175     Next, copy your files on an installed mailman tree, and run
 176     bin/transcheck XX, where XX is your country code.
 177
 178     No warning should appear (but maybe some warning is ok, if you really
 179     know what you're doing).
 180
 181     Now, try to run your translation (add an "add_language" line to
 182     Mailman/Defaults.py) and check the many scattered pieces blend
 183     together well.  Sometimes you'll need some adjustment.
 184
 185     When you're satistied, pack up a tar.gz with the following structure:
 186
 187     messages/XX/LC_MESSAGES/mailman.po
 188     templates/XX/admindbdetails.html
 189     templates/XX/admindbpreamble.html
 190     .
 191     .
 192     templates/XX/userpass.txt
 193     templates/XX/verify.txt
 194
 195     (XX is your country code) and send it to Barry Warsaw.  Do not
 196     include the mailman.mo file if you can help it.
 197
 198     By that time, your translation could be somewhat obsolete, because
 199     templates and mailman.pot could have been evolved meanwhile.
 200
 201     Don't panic.
 202
 203     You'll need to check diffs to find what changed and how, so that
 204     you can easily update your files.
 205
 206     Save everything everytime, you'll need it.
 207
 208
 209 \f
 210 Local Variables:
 211 mode: text
 212 indent-tabs-mode: nil
 213 End: