1## How to Contribute
2
3There are two ways to contribute to the user manual of Kraft.
4
5### Work on the English Manual
6
7Just improve the English Manual that is stored in the file `kraft.adoc` in this directory.
8With that you can concentrate on writing and do not deal with scripting etc. Content rules!
9Please send your changes either as pull request, or via email to the project maintainers. They will care for the rest.
10
11Every change that is done to the master document in English language will be translated
12to all the other internationalized versions of the doc.
13
14### Translate
15
16The translations of Kraft will be maintained on Transifex, just like the normal
17software strings. Check there for translation tasks.
18
19## Internationalization of the Manual
20
21This is based on the great [doc here](https://github.com/KiCad/kicad-doc/blob/master/doc_alternatives/README.adoc).
22
23The process of internationalization of the Kraft Manual is done in different steps.
24
25It relies on the the same gettext process that is also used for the normal software
26strings. To extract the strings from the manual, the great utility po4a is used.
27
28### Step 1: String Template Extraction
29
30This is extracting strings ready for the gettext system. This needs only to
31be done once. Later, the pot file is only going to be updated.
32
33```
34  po4a-gettextize -f asciidoc -M utf-8 -m kraft.adoc -p po/kraft.pot
35```
36
37The update works with the command msgmerge:
38
39```
40  msgmerge -vU kraft-de.po kraft.pot
41```
42
43### Step 2: Translation
44
45Copy the template into the nationalized version:
46
47`cp po/kraft.pot po/kraft-de.po`
48
49and use the gettext editor you like or upload to Transifex.
50
51Keep in mind that snapshots images should be nationalized. I suggest to
52create a internationalized image dirs such as:
53```
54  images
55  images-de
56  images-es
57```
58This way untranslated images fallback to English images. po4a
59correctly translate image reference to enable the fallback.
60
61### Step 3: Produce Internationalized Master Documents
62
63```
64  po4a-translate -f asciidoc -M utf-8 -m kraft.adoc -p po/kraft-de.po -k 0 -l kraft-de.adoc
65```
66
67### Step 4: Produce all Kind of Internationalized Output Formats
68
69```
70  asciidoc -a lang=de kraft-de.adoc    #convert into html
71  a2x -a lang=de -f pdf kraft-de.adoc  #convert into pdf
72  a2x -a lang=de -f epub kraft-de.adoc #convert into epub
73```
74
75### Step 5: Update Translations
76
77With the following command the .po file will be updated automatically.
78
79```
80  po4a-updatepo -M utf8 -f asciidoc -m kraft.adoc -p po/kraft-de.po
81```
82
83### Step 6: Loop
84
85repeat from step 2
86