From c2fa3180669f4649fb74f1fed372956fc9152de1 Mon Sep 17 00:00:00 2001
From: Bandie <bandie@chaospott.de>
Date: Sat, 22 Sep 2018 00:26:08 +0200
Subject: [PATCH] Created How to translate (markdown)

---
 How-to-translate.md | 87 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 How-to-translate.md

diff --git a/How-to-translate.md b/How-to-translate.md
new file mode 100644
index 0000000..f2b1f94
--- /dev/null
+++ b/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`.
+