Translating Docs - Revision history

Vollstrecker: Corrected some typos and added diff example.

2010-04-30T06:53:37Z

Corrected some typos and added diff example.

Vollstrecker at 18:19, 4 January 2010

2010-01-04T18:19:41Z

Vollstrecker: Typos and headlines

2010-01-04T14:39:37Z

Typos and headlines

Vollstrecker: Created page with ' '''English''' | Deutsch = Translating aMule's manpages using po4a = Starting with svn rev. 9932 there is a directory called docs/man/…'

2010-01-04T14:35:20Z

Created page with '<center> '''English''' | Deutsch </center> = Translating aMule's manpages using po4a = Starting with svn rev. 9932 there is a directory called docs/man/…'

New page

<center>
'''English''' |
[[Translating_Docs-de|Deutsch]]
</center>

= 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:

# Don't remove or add any information (beside the addendum), if you want to do so, change the english version
# Make sure your editor produces files in UTF-8 encoding
# Don't remove any special chars
# po4a will ignore every file, where not at least 80% are translated

== Preparing ==
To start a translation you have three possible scenarios:

# There is already a translated .po
# There is no translated .po, but you have po4a installed
# 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 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 [[Translations|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 [[forum]]s 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.

# E-types - A capital E starts a special symbol, that uncoded has different meanings.
## E<lt> will print the "<"-sign
## E>lt> will print the ">"-sign
# Textformat - For textformatting there are 3 different types of lonely capital letters.
## B<''Text''> - Indicates that the text between < and > will be printed bold
## I<''Text''> - Indicates that the text between < and > will be printed italic
## 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 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 trabslated docs. You can check now how they look by just typing

man <translated-page>

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

# docs/man/amule.<your-lang>.1
# docs/man/amulecmd.<your-lang>.1
# docs/man/amuled.<your-lang>.1
# docs/man/amulegui.<your-lang>.1
# docs/man/amuleweb.<your-lang>.1
# docs/man/ed2k.<your-lang>.1
# src/utils/aLinkCreator/docs/alc.<your-lang>.1
# src/utils/aLinkCreator/docs/alcc.<your-lang>.1
# src/utils/cas/docs/cas.<your-lang>.1
# src/utils/wxCas/docs/wxcas.<your-lang>.1
# 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 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 it ends with
a space and a backsplash (" \").

If you add your lang at the end, at the space and backslash 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.

@@ Line 147: / Line 147: @@
 # src/utils/xas/docs/xas.&lt;your-lang&gt;.1
-Now you just have to let make know that you did this job, by adding the translated file the list of files.
+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:
@@ Line 158: / Line 158: @@
 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 it ends with
+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, at the space and backshlash to the line above.
+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.

@@ Line 19: / Line 19: @@
 # Don't remove any special chars
 # po4a will ignore every file, where not at least 80% are translated
 = Preparing =
@@ Line 31: / Line 32: @@
 == Preparing without translated .po but installed po4a ==
-Change to docs/man/ dir, open the file po4a in your favorite texteditor. The first line is:
+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
@@ Line 114: / Line 115: @@
 Again you have more than one option.
-If you used an existing translation, you can just post the updated .po to forums, and someone will commit it.
+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
@@ Line 128: / Line 129: @@
   po4a po4a.config
-again, to create your trabslated docs. You can check now how they look by just typing
+again, to create your translated docs. You can check now how they look by just typing
   man &lt;translated-page&gt;

@@ Line 4: / Line 4: @@
 </center>
-= Translating aMule's manpages using po4a =
+'''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
@@ Line 11: / Line 12: @@
 but I strongly encourage you to install it, because it's speeds thing up and make everything a lot easier.
-== Rules ==
+= Rules =
 Before you start, here  are some basic rules you need to follow:
@@ Line 19: / Line 20: @@
 # po4a will ignore every file, where not at least 80% are translated
-== Preparing ==
+= Preparing =
 To start a translation you have three possible scenarios:
@@ Line 26: / Line 27: @@
 # There is no translated .po and you don't have po4a installed
-=== Preparing with already translated .po ===
+== Preparing with already translated .po ==
 No preparation needed, start translating.
-=== Preparing without translated .po but installed po4a ===
+== Preparing without translated .po but installed po4a ==
 Change to docs/man/ dir, open the file po4a in your favorite texteditor. The first line is:
@@ Line 47: / Line 48: @@
 For sure, you can follow the steps described in the next section for preparation, too.
-=== Preparing without translated .po but no installed po4a ===
+== Preparing without translated .po but no installed po4a ==
 Change to docs/man/po/ dir, copy manpages.pot to your languages .po file. For example:
@@ Line 55: / Line 56: @@
 used po4a when submitting.
-== Translating ==
+= Translating =
 Just use your favorite tool for editing .po files, like you would use for [[Translations|Translate aMule into your native language]].
 As always, you have to keep formating chars as they are, and just translate the text in there.
@@ Line 69: / Line 70: @@
 You'll find formatting chars on almost every line. If in doubt, use the folling list, or just ask on [[forum]]s or [[IRC]].
-== Formatting Charackter of po4a ==
+= 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.
@@ Line 81: / Line 82: @@
 ## R&lt;''Text''&gt; - Indicates that the text between &lt; and &gt; will be printed roman (the usual font)
-== The addendum ==
+= 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
@@ Line 110: / Line 111: @@
   Diese manpage wurde &uuml;bersetzt von Vollstrecker &lt;amule@vollstreckernet.de&gt;
-== Submitting the translation ==
+= Submitting the translation =
 Again you have more than one option.
@@ Line 157: / Line 158: @@
 If you add your lang somewhere in the middle to preserve the alphabetical order, make sure it ends with
-a space and a backsplash (" \").
+a space and a backshlash (" \").
-If you add your lang at the end, at the space and backslash to the line above.
+If you add your lang at the end, at 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.