So you want to translate Mailman...

Great! Welcome to the Mailman Translation Project!

Step-by step translation

Firstly, as mentioned on the main i18n page, it's crucial that you join our mailman-i18n mailing list. This is where we communicate with each other. You'll miss out on important announcements and support if you are not a member of the list, so please make sure you have joined mailman-i18n, before reading any further.

Now, whether you're helping to work on an existing language translation, or whether you're creating a new language translation for Mailman, everything starts at...

The Source

Each Mailman release is made available as a tarball (file ending in .tar), currently from Mailman's project page at Launchpad. Start by downloading the Mailman source files: Choose the most recent version in the 2.1 series (Mailman 3 is not ready for translation yet and will use Launchpad for translation), and click it's name to download it. The file you download will usually have a name like mailman-VERSION.tgz, showing that this is mailman, which version it is, and that it is a .tar package compressed with the gzip program).

Decompress the package of source files, as you usually decompress files you download. The resulting directory (mailman-VERSION) contains all the source files for the Mailman program, so many of them don't require translating. However, you will need them to compile the program and test it.

For translation, we focus on the two directories /messages and /templates.

Where your translation lives

If you're working with an existing language translation, it will probably be in the package already, and/or you may need to copy more recent translation files into the directories for your language. This section describes the structure for translation files.

In /messages, there should be an /xx directory for each language supported, where xx is your ISO-639 language code.

• If there is not a directory for your language code, please create an empty directory /xx for your language, e.g. /vi for Vietnamese.

Inside each language directory /messages/xx, there should be a sub-directory called LC_MESSAGES.

• If this directory does not yet exist, please create it. This will give you the structure /messages/xx/LC_MESSAGES, e.g. /messages/vi/LC_MESSAGES. If you look at any of the other language-directories, you'll see they have the same structure.

Inside LC_MESSAGES, the existing languages should have the file mailman.po. This is the file containing all of the strings (text messages: buttons, instructions, labels, error messages etc.) found in the Mailman interface.

• If this file does not yet exist, copy the messages.pot file from the main directory into LC_MESSAGES. Rename it to messages.po. This gives you the structure /messages/xx/LC_MESSAGES/messages.po, e.g. /messages/vi/LC_MESSAGES/messages.po.

You will be translating this file, but first, we need to create a second internal structure for the other translation files. There are over 40 HTML and text templates in Mailman, which are used to display webpages, and to send automatic administration emails. Don't be intimidated by the size of the task: many of these files are actually very small. Just take it one step at a time.

For now, each language needs its own directory to hold its translations of these templates. Where the interface messages were in /messages, the html and text templates are in /templates.

Inside the /templates directory, again, each language should have its /xx directory, named for its language code.

• If this directory doesn't exist for your language, please create it.

This will give you /templates/xx, for example, /templates/vi. This directory holds all the translated templates. Where do we get them?

Unlike mailman.pot, the original (English) version of the interface file, all the original (English) versions of the HTML and text templates are in the en (English) directory in templates, in /templates/en.

• If your language directory does not hold all these templates, please copy the missing templates over from the /templates/en directory.

That might be a few extra templates, or it might be all of them, if you are starting a new translation. Just copy them over to your language directory. You don't need to change their names at all, in fact, it's important that you don't change their names, or Mailman won't be able to use them. Mailman knows what they are. Their location in your /xx directory identifies them as translations in your language.

So, once you have created these two structures, Mailman has two places to look for your translations. It will get the interface "strings" from the mailman.po file in /messages/xx/, and the HTML and text templates from all the files in /templates/xx.

Now, you're ready to start translating!

Backup, backup, BACKUP!

However, before you get started, there's one very important reminder. Data on a computer can become corrupted, accidentally deleted or damaged in some other way. Always make a backup copy of your work. You don't want to have to do it all again.

You can run a backup program that will backup (make an extra copy of) all the files you choose, every day (or other time-frame). You can also manually make a backup copy of your translations. However you do it, please backup your work! Back it up, preferably on another disk, and make hard copies (e.g. on CD) as well. Especially before you have uploaded your translations elsewhere, these are the only copies of your work. Take care of them. They represent your effort, which you don't want to waste.

And Save often.

Translating

If you have some experience in translating PO files, text or HTML files, there is nothing unusual about the Mailman files. For newer translators, and those who would like some extra information, there are some resources listed further down.

Basically, the translation process is:

1. Look at the original text

2. Think of the best way to express that in your language. This is not necessarily by translating each word, but by translating what the string is trying to say. For example, you will probably not get a good translation by substituting the words in your language for "zombie process", but when you look up a zombie process (see #Resources below) and find out that it is a process that has died, and won't go away, you can find a way to express that in your language. Always think about the job the string has to do. Make it do that job in your language.

3. If you don't understand the string, firstly try looking up the words (#Resources), and/or asking other translators for your language. If you are still puzzled, please ask on the mailman-i18n mailing list: that's what it's for. Some of the Mailman strings are complex, so please don't feel shy about asking questions: we all do!

4. Enter your translation.

and you simply repeat that process until you are finished.

Take your time, don't push yourself. The Mailman interface file (mailman.po) is quite long and complex, so it's much better to spend some time on it, then take a break, ask questions, do something else for a while, then come back to it. Don't try to do it all at once, or under time pressure. Creating language is a work of art. It takes time, effort and ability. Value these things, and don't try to push them. Make sure you allot enough time to do the job well. A bad translation is really worse than no translation at all, because it gives the user incorrect information. If you want to do this at all, you want to do it as well as you can.

Another thing to remember: you can submit partial translations! Any template or message that is not translated will get printed in English by Mailman. That may not be ideal for your language, but it allows you to see the progress of your work. If your translation is brand new, feel free to submit it at some point where you've made enough progress that others can be inspired to help you out. The Mailman developers will integrate your language if there is a reasonable amount of content in there, even if it isn't 100% complete.

I'm finished!

Take a deep breath and have a break.

When you come back, now it's time to check your translation. You can check mailman.po by running msgfmt -cv -o /dev/null FILENAME (see #Resources), and the HTML and text templates by viewing them in your browser and text editor. Make sure there are no errors, before you submit your files. If there are any remaining errors, they will break Mailman, and your translation will not be used.

You can also build Mailman to test your translation. That's why you need to keep all Mailman's source files.

How do I send in my translation?

You can submit the messages and templates translations separately, or together. You might finish one before the other, or you might have finished some of the templates. Please send in what you have finished: you can continue to work on it afterwards, or at another time.

Please don't send in separate files. The best way to send in your translations is to create a Bazaar branch. you can then upload it to launchpad or make it publicly available in some other way and then notify the mailman-i18n mailing list of its availability.

Alternatively, you can send in the whole /messages/xx and/or templates/xx directories, as a tarball that can be unpacked at the top of the Mailman source tree. Please compress directories before sending (gzip or bzip are preferred). The Mailman developers will unpack your tarball at the top of the tree, and your submitted files will overwrite any files in the tree. Assuming everything builds, they will then commit your changes. You can submit the compressed translation package to the launchpad tracker.

Are you submitting translations often?

If so, and if you're comfortable with source control, you may want to request bzr commit access to Mailman. This gives you direct access to the Mailman code, so it's a privilege you must take very seriously. It also means you can update your translations very quickly.

Optimally, one person in your team should have this access, so s/he can manage the uploads. If nobody is doing this yet in your team, consider learning how to use bzr (Bazaar). It's not difficult, and it's a key tool in open-source translation. Please see the bzr links in #Resources.

Are you adding a new language?

If you're translating Mailman into a new language, one into which it hasn't been translated before, you need to remember to tell Mailman about it.

Your team-leader, or whoever has SVN access, needs to add this information to the Mailman files. If nobody in your team has bzr access yet, you need to ask on the mailman-i18n list for someone to add your language.

Mailman, being a program, only knows what it reads in its source code. Even if your translation is placed in its /po directory, Mailman may not know that it's supposed to use your translation.

It gets a lot of its configuration information from a file called Defaults.py.in : look in /Mailman/Defaults.py.in. Open this file in a text editor. (This information varies slightly between stable (Mailman 2.1.x) and trunk (Mailman 2.2.x.)

For Mailman 2.1.x

Find the add_languages line, the section at the end of the file. You'll see a list of languages.

Each language entry looks like:

add_language('xx', _('NAME'), 'ENCODING')

For example,

add_language('uk', _('Ukrainian'), 'utf-8')

Simply copy one of these lines, paste it in where your language would fit in the alphabetical list, then substitute your language two-letter code, name and character set for the copied ones.

For Mailman 2.2.x

Find the LANGUAGE_DICT section, nearly at the end of the file. You'll see a list of languages.

Each language entry looks like:

'xx': (_('NAME'), 'ENCODING'),

For example,

'uk': (_('Ukrainian'), 'utf-8'),

Simply copy one of these lines, paste it in where your language would fit in the alphabetical list, then substitute your language two-letter code, name and character set for the copied ones.

Save your files, commit your changes, and your translation will now be used by Mailman.

How do I update my translations?

Mailman is continually being developed and improved. This means that the messages and templates will change, usually not very much. Some version changes may not change the translatable information at all. So, how do we know what has changed?

The new mailman.po file will automatically show any changes, any empty strings or "fuzzy" (incomplete) strings. Your editor (#Resources) should show a summary of those changes. For example, my translation editor, LocFactoryEditor on Mac OSX, shows a summary in the toolbar, what percentage of the file has been translated, and in the side-bar, how many fuzzy strings, how many untranslated strings etc.

So, then all you need to do is update your translation of the mailman.po file, and submit messages/xx/mailman.po again.

It's a bit more fiddly to show changes in the HTML and text templates. I'm looking into finding an easier way, but right now, probably the easiest way is to diff the files. "diff" tools "find differences". For example, my text editor, BBEdit will compare two directories of files. Your editor will probably do the same. Once you compare the two /templates/en directories to find files where the original text has changed, you can update those files in the /templates/xx directory for your language, and submit that directory again.

Tip for diffing

When you diff translation files (and this also applies to long and complex strings in PO files, where a "fuzzy" tag just tells you the whole long string has changed somewhere), you really need a word-by-word diff. And you can do one.

Normally, to compare two files, and find the differences between them, you run "diff":

diff -u old_file new_file

which shows the output in your terminal. To output the results to a file:

diff -u old_file new_file >output_file.diff

but this shows whole paragraphs as the difference. It's not specific enough. With the wdiff tool, you can compare word-by-word.

Use wdiff instead of "diff" in the syntax above, and you will see an actual word-by-word comparison. This is a powerful tool for translation.

By using:

wdiff -l old_file new_file |less

you can see a visual reference in the terminal (bold text and underscore text showing changes).

There is more information available on wdiff.

A good translation editor will also compare previous (msgid-previous) and current (msgid) original strings, using wdiff or another word-by-word comparison process. My editor does this, and highlights the differences. This makes updates much easier. If your translation project is not yet using the msgid-previous feature of gettext, they should upgrade to it, as it ensures more efficient and accurate translation updates.

Resources

Both new and experienced translators need resources to do the job. Mailing lists are our main source of communication, and you will find that there are mailing lists for each project, and mailing lists in your language for your specific language team. For example, have a look at the list of language teams at:

• The Translation Project

• Debian

• Gnome

• KDE

• Ubuntu

and join at least one of these. This will give you contact with other translators in your language group, so you can support each other, and deal with issues specific to your language as they come up. In particular, now Mailman is also using the Launchpad translation system, you need to join the Mailman team for your language on Launchpad. If there is not yet a team for your language within the main Mailman Translators team, please ask on the mailman-i18n mailing list for it to be set up. Then you can join it!

The Translate Wiki is a central resource for translators. There, you will find descriptions of the main projects, comparisons of translation editors and other tools, explanations of how to translate files, the different types of syntax, how to handle variables, and how to use the gettext tools (e.g. running the msgfmt check).

See especially the Localization Guide (including the Translation Project Howto, which includes some useful general introductory information for new translators), and the Resources page, which includes links to dictionaries and other references which you can look up, to find the information you need.

Between your language team(s), and the Translate Wiki, you should have access to a wide range of resources that help you do the job.

You can also find information on how to use bzr in the Translate Wiki, and from:

• Download bzr

• Introducing bzr

• bzr Tutorial

• bzr tips for SVN users

Good luck with your translations!