Apply 80_fix_string_search.patch
[mspang/vmailman.git] / 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: