Created How to translate (markdown)

How-to-translate.md

@@ -0,0 +1,87 @@
+This article will show you how you can help to translate this project.
+
+## Preparation
+1. Install git and gettext.
+2. Fork this project.
+3. Clone your fork on your computer.
+
+
+We will begin with the simplest translations:
+
+## Translation within the program - gettext
+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 some information about you. It will generate a file ending with `.po` which you want to translate.
+
+### .po translation convention
+- Please don't translate words with big letters, for example `ERROR`.
+- 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**:
+```
+msgid "Key? "
+msgstr "Schlüssel? "
+```
+
+#### c-format
+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
+Sadly there's no system implemented yet to translate man pages. It means you have to do it by hand.
+
+### man pages location
+The man pages are at
+```
+src/pam_panic/man/man8
+src/pam_panic_pw/man/man1
+```
+
+### Preparation
+For pam_panic:
+1. Go to `src/pam_panic/man`.
+2. Make a new directory called like your ISO locale. (de for German, es for Spanish, ...). `mkdir de`.
+3. Copy recursively the man[digit] to your directory which you just created. `cp -r man8 de`.
+
+For pam_panic_pw:
+1. Go to `src/pam_panic_pw/man`.
+2. Make a new directory called like your ISO locale. (de for German, es for Spanish, ...). `mkdir de`.
+3. Copy recursively the man[digit] to your directory which you just created. `cp -r man1 de`.
+
+### Translate
+Try to translate the man page. The man page file is ending with a digit like `pam_panic.8`.
+You will see something like `\fBpam_panic\&.so\fR` which looks weird:
+- `\fB` and `\fR` are formatting control characters. Just try to adopt them.
+- `\&.` is actually a `.`. You need to escape dots like this. Sadly.
+
+### Integration of the man pages
+- Open `src/pam_panic/man/Makefile.am` and put your new man page path into the `nobase_dist_cant_believe_its_not_man_DATA` list. Note that you have to add a `\` at the end of the last entry.
+- Same thing for `src/pam_panic_pw/man/Makefile.am`.
+