Translating Docs

English | Deutsch

Translating aMule's manpages using po4a

Starting with svn rev. 9932 there is a directory called docs/man/po/ in the sources. In this directory you'll find a file named manpages.pot, and corresponding .po files for the languages they are translated in. With these files, you can contribute, so people of your language will have manpages in the native tonque. This arcticle describes, how to do this. It's not needed to install po4a to translated the docs, but I strongly encourage you to install it, because it's speeds thing up and make everything a lot easier.

Rules

Before you start, here are some basic rules you need to follow:

1. Don't remove or add any information (beside the addendum), if you want to do so, change the english version
2. Make sure your editor produces files in UTF-8 encoding
3. Don't remove any special chars
4. po4a will ignore every file, where not at least 80% are translated
5. Make sure that neither you nor your app doesn't remove trailing spaces

Preparing

To start a translation you have three possible scenarios:

1. There is already a translated .po
2. There is no translated .po, but you have po4a installed
3. There is no translated .po and you don't have po4a installed

Preparing with already translated .po

No preparation needed, start translating.

Preparing without translated .po but installed po4a

Change to docs/man/ dir, open the file po4a.config in your favorite texteditor. The first line is:

[po4a_langs] de es eu fr hu

Just add your language to this line (alphabetical order please). To add pt_BR it would look like:

[po4a_langs] de es eu fr hu pt_BR

Now just run

po4a po4a.config

in that dir, and you'll find your newly created .po in po/. In our example po/manpages-pt_BR.po

Now you can start translating. For sure, you can follow the steps described in the next section for preparation, too.

Preparing without translated .po but no installed po4a

Change to docs/man/po/ dir, copy manpages.pot to your languages .po file. For example:

cp manpages.pot manpages-pt_BR.po

for translating to pt_BR local. Now you can start translating, but don't forget to mention that you don't used po4a when submitting.

Translating

Just use your favorite tool for editing .po files, like you would use for Translate aMule into your native language. As always, you have to keep formating chars as they are, and just translate the text in there.

For example the original line:

msgid "B<[ -w> I<E<lt>pathE<gt>>, B<--use-amuleweb>=I<E<lt>pathE<gt>> B<]>"

becomes in german translation:

msgstr "B<[ -w> I<E<lt>PfadE<gt>>, B<--use-amuleweb>=I<E<lt>PfadE<gt>> B<]>"

You'll find formatting chars on almost every line. If in doubt, use the folling list, or just ask on forums or IRC.

Formatting Charackter of po4a

The formatting chars in po4a's po file are a bit different than the ones used in the original manpage, therefor here is a hopefully complete list of the chars you might find.

1. E-types - A capital E starts a special symbol, that uncoded has different meanings.
   1. E<lt> will print the "<"-sign
   2. E>lt> will print the ">"-sign
2. Textformat - For textformatting there are 3 different types of lonely capital letters.
   1. B<Text> - Indicates that the text between < and > will be printed bold
   2. I<Text> - Indicates that the text between < and > will be printed italic
   3. R<Text> - Indicates that the text between < and > will be printed roman (the usual font)

The addendum

An Addendum is a file that contains additional informations in your language, that are not included in the original documents. That is the place for telling the world that you did that great thing and translated the docs.

The addendum is placed in a file called manpages-<your-lang>.add in docs/man/po/ directory.

The first line of this file contains the place where to add the information. This is supposed to be the bottom of the translated doc.

• DONT'T CHANGE THE FIRST LINE OF THIS FILE

The best solution is to copy an existing file, and change the contents. To get a linebreak, you just use an empty line. If you don't place an empty line between two lines of text, they will be printed right behind to peceeding one.

Now you can add a line

Translated by <your-name>

or if there exist already one like this

Updated by <your-name>

in your language. For example the german addeddum file look like this:

PO4A-HEADER:mode=after;position=^\.TH;beginboundary=^FakePo4aBoundary

Diese manpage wurde übersetzt von Vollstrecker <amule@vollstreckernet.de>

Submitting the translation

Again you have more than one option.

If you used an existing translation, you can just post the updated .po and .add to forums, and someone will commit it. This isn't the best way, because you have to rely on someone that has commit rights to svn and po4a installed. Most likely someone with po4a installed will create all needed files, send them back to you for checking if everything looks like you expect it, and someone else will commit the changes.

A better solution would be, to install po4a, and use it for the whole process. Po4a is available on most distros, just check your distros package manager.

If you didn't already add your lang into po4a.config now is the right time for doing this.

Now just run

po4a po4a.config

again, to create your translated docs. You can check now how they look by just typing

man <translated-page>

You should check all the pages. Here's a list:

1. docs/man/amule.<your-lang>.1
2. docs/man/amulecmd.<your-lang>.1
3. docs/man/amuled.<your-lang>.1
4. docs/man/amulegui.<your-lang>.1
5. docs/man/amuleweb.<your-lang>.1
6. docs/man/ed2k.<your-lang>.1
7. src/utils/aLinkCreator/docs/alc.<your-lang>.1
8. src/utils/aLinkCreator/docs/alcc.<your-lang>.1
9. src/utils/cas/docs/cas.<your-lang>.1
10. src/utils/wxCas/docs/wxcas.<your-lang>.1
11. src/utils/xas/docs/xas.<your-lang>.1

Now you just have to let make know that you did this job, by adding the translated file to the list of files. To do so, open the file Makefile.am which is in every dir where the manpages you created reside. In there, you'll see some thing like:

EXTRA_DIST = \
       amule.1 amuled.1 amulecmd.1 amulegui.1 amuleweb.1 ed2k.1 \
       amule.de.1 amuled.de.1 amulecmd.de.1 amulegui.de.1 amuleweb.de.1 ed2k.de.1 \
       amule.es.1 amuled.es.1 amulecmd.es.1 amuleweb.es.1 ed2k.es.1

Just add the files of this dir with your language.

If you add your lang somewhere in the middle to preserve the alphabetical order, make sure the line ends with a space and a backshlash (" \").

If you add your lang at the end, add the space and backshlash to the line above.

If they all look correct, you can create a diff of the whole source-tree and submit it to the forums.

To create a diff, you need a clean source-tree beside your modified one, so easiest way is, to rename the tree that contains your changes to something like "amule-changed" and reextract the tarball with which you startet. Then just run:

diff -Naurd <clean-source-tree> <modified-source-tree> > translation.diff

Now you can submit translation.diff to forums.