Updated How to translate (markdown)

How-to-translate.md

@@ -1,15 +1,17 @@
 This article will show you how you can help to translate this project.
 
-## Preparation
+# General preparation
 1. Install git, gettext and po4a.
 2. Fork this project.
 3. Clone your fork on your computer.
 4. (Optional:) Get an editor for po files or use an online service for it.
 
+Are you new to .po files? You might want to read about [The .po structure](https://github.com/pampanic/pam_panic/wiki/The-.po-structure).
 
-We will begin with the simplest translations:
 
-## Translating the program
+# Translating the program
+
+## Steps to do
 1. Change into the `po` directory.
 2. Run `msginit --locale=<your locale here>` (for example `msginit --locale=de_DE.UTF-8`). This will ask for your mail adress. It will generate a file ending with `.po` which you want to translate.
 3. Change the header from `"Last-Translator: <your.mail@address.tld>\n"` to `"Last-Translator: Your Name <your.mail@address.tld>\n"`
@@ -17,59 +19,21 @@ We will begin with the simplest translations:
 5. Add your language to the `LINGUAS` file.
 
 
-
+## Translation notes: pam_panic program 
-
-### .po gettext translation convention
 - Please fill out translations even if they're the same, like digits.
-- Please don't translate words with big letters, for example `ERROR`.
+- Please keep the formatting of the words like in the original; e.g. `ERROR` should be kept uppercase.
 - Please don't translate words in surrounding of `\"`, for example `\"allow\"`.
 - Please include all spaces and special characters like in `msgid`.
 
-### .po structure
-The .po file will contain a structure like
-```
-msgid "Key? "
-msgstr ""
-```
 
-Your task will be to put your translation in the quotes of `msgstr` **including all spaces and special characters**:
+# Translating the man pages
-```
-msgid "Key? "
-msgstr "Schlüssel? "
-```
 
-#### c-format
+## Steps to do
-There are also c-Strings which look like
-```
-#, c-format
-msgid "Please run this program under root. Write access to %s is mandatory.\n"
-```
-which you'd have to translate including %s (which is a place holder) and \n (which is a control character).
-
-#### Big messages
-Sometimes there are big messages like
-```
-msgid ""
-"ERROR: Arguments invalid. Note that \"allow\" and \"reject\" must have a "
-"valid GPT UUID."
-```
-
-Just do it the same:
-```
-msgstr ""
-"ERROR: Foo foo blablabla \"allow\" und \"reject\" foo awoo woo yip "
-"ararara yip yap GPT UUID."
-```
-
-
-## man pages
-
-### Translating the man pages
 1. Change into the `po4a` directory.
 2. Run `msginit --locale=<your locale here>` (for example `msginit --locale=de_DE.UTF-8`). This will ask for your mail adress. It will generate a file ending with `.po` which you want to translate.
 3. Change the header from "Last-Translator: <your.mail@address.tld>" to "Last-Translator: Your Name <your.mail@address.tld>"
 
-### .po4a man page translation convention
+## Translating notes: man pages
 - Please fill out translations even if they're the same, like digits or other things.
 - Translate `__PAMPANICSO__`, `__PAMPANICPW__`, `__PPASSFILE__` and other weird looking stuff exactly like they're looking.
 - Please don't translate the words "reboot", "poweroff", "serious", "allow" and "reject", but include them in your text. Those are surrounded by escape sequences like "B<reboot>" (which means "make the word "reboot" big).
@@ -83,13 +47,13 @@ msgstr ""
   Put your own name and mail address into the msgstr, with a sentence like `This man page has been translated by Name E<lt>mail@address.tldE<gt>` (translated of course).
 
 
-### Integration of the man pages
+## Integration of the man pages
 
 - Open `src/pam_panic/man/Makefile.am` and put your new language in the `nobase_dist_cant_believe_its_not_man_DATA` list. Note that you have to add a `\` at the end of the last entry. It will look like "<yourISOlanghere>/man8/pam_panic.8.gz \".
 - Same thing for `src/pam_panic_pw/man/Makefile.am`.
 
 
-## Send a pull request
+# Send a pull request
 
 After you're satisfied with your work, make a pull request.