1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
<h1>Translator Guide</h1>
<p>If you would like to translate any part of the <a href="http://mongrel2.org/wcontent">wiki</a> or the <a href="http://mongrel2.org/static/mongrel2-manual.html">manual</a> to another language then there are just a few things you need to do. First let's cover some things to consider before starting:
</p>
<ol>
<li>Make sure that the there isn't a translation already. Usually the top of the page lists the translations available.</li>
<li>You have to agree to keep any nationalistic, racist, or ethnocentric concerns out of your language choice. This means that if your language choice is controversial because of war, genocide, oppression, or similar concerns then I'll remove it.</li>
<li>The most popular document to translate is the <a href="http://mongrel2.org/wiki?name=GettingStarted">GettingStarted</a> wiki page. I would recommend starting with that.</li>
<li>You can also translate any of the other wiki pages, as most of them are short and easy to do.</li>
<li>There are also people interested in translating the full <a href="http://mongrel2.org/static/mongrel2-manual.html">manual</a> but this is a big task. If you want to do the manual, consider taking it slow and taking your time.</li>
<li>Translating wiki pages means you need to know HTML.</li>
<li>Translating the manual requires knowing TeX and having a Full <a href="http://tug.org/texlive/">TexLive</a> install, which can take a while.</li>
</ol>
<p>If you understand all of the above then here's how I recommend you do your first translation:</p>
<ol>
<li>Go through the <a href="http://mongrel2.org/wiki?name=GettingStarted">GettingStarted</a> wiki page and make sure you can follow it.</li>
<li>Follow the <a href="http://mongrel2.org/wiki?name=ContributorInstructions">ContributorInstructions</a> and get the Mongrel2 source checked out with <a href="http://fossil-scm.org">fossil</a>.</li>
<li><b>DO NOT INSTALL FOSSIL WITH YOUR OPERATING SYSTEM'S PACKAGE MANAGER.</b> The ContributorInstructions already tell you this, but this is the #1 mistake people make.</li>
<li>Once you have your own copy of the latest Mongrel2 code, go into the <b>docs</b> directory and create a directory with your language's closest <a href="http://en.wikipedia.org/wiki/Top-level_domain">TLD</a>. Look at the other directories to see how it would work.</li>
<li>Now make a <b>wiki</b> directory there. For example, if I wanted to make a translation for German id make <b>docs/de/wiki</b>.
<li>Take the existing English wiki page from <b>docs/wiki</b> and copy it to your new wiki directory.</li>
<li>Do the translation.</li>
</ol>
<p>If you are ready to translate the whole manual here are some tips to help you get started quickly:</p>
<ol>
<li>Create a directory for your translation like <b>docs/de/manual</b> (you
replace <b>de</b> with your language) and copy all the files from
<b>docs/manual</b> to this directory.</li>
<li>As you see the manual is split into a set of <b>.tex</b> files. To get the
<b>.pdf</b> file you have to instruct TeX to put them all together, build and
output the guide in PDF format. To do that just issue <b>make book-final.pdf</b>
in the command line.</li>
<li>At this stage it will complain about not being able to find some files. This
is normal. The thing is that the manual refers some source code files and the
paths to these files are relative to the location of the manual. Since you have
copied the manual one level deeper in the filesystem (docs/manual to
docs/de/manual) the paths are now broken. To fix them you have to prepend
../ For now you can ignore the warnings by hitting Enter. But as soon as you
build often and it gets really annoying just fix them up once and for all.</li>
<li>It <i>might</i> fail to build due to the incompatibility of the typeface
with your language. This is individual for each language so the only practical
advice is to search the internet on how to make TeX be nice with it.</li>
<li>To build <i>and</i> open run <b>make view</b>. Though you need to have
<a href="projects.gnome.org/evince/">evince</a> installed.</li>
<li>Once you have it open two things will grab your attention: the margins are
much wider compared to the ones you see in the original manual you have
downloaded from the site; and there is no table of contents.</li>
<li>There is lots of whitespace because by default the manual is optimized for
print, not for the screen. To change this uncomment the line
<b>%\usepackage{savetrees}</b> in the <b>preamble.tex</b>.</li>
<li>To generate the TOC you have to build it <i>twice</i>. Here is how you do
it: <b>make book-final.pdf</b>, then <b>rm book-final.dvi book-final.pdf</b> and
<b>make book-final.pdf</b> again. Yep, sounds strange. But once you have an idea
about how TeX works it's not that surprising. During the first run TeX does not
yet know which page every title will end up on. So it only reserves some space
for the TOC (you will see a blank page) and writes nothing to it. During the
second run the titles are all anchored and filling out this blank page is a
snap.</li>
<li>Finally, repeat this cycle: translate a subsection, generate the .pdf file,
open it and proofread the translated snippet, correct if necessary. When you
have a .tex file translated, commit it / send via email (below) and move on to
the next one.</li>
</ol>
<p>Once you have your translation, you just have to submit it to the project. There's two ways to do this:</p>
<ol>
<li>Email it to the <a href="mailto:mongrel2@librelist.com">mongrel2@librelist.com</a> mailing list as an <b>attachment</b> and one of us will put it in. This is the best if you just do one wiki page and don't plan on doing lots of translations.</li>
<li>Put your fossil repository online using <b>fossil serve</a> as described in <a href="http://mongrel2.org/wiki?name=ContributorInstructions">ContributorInstructions</a> and ask one of us to pull from it. This is best if you want to do many translations, or maybe the manual. If you show active involvement we'll give you contributor access to the main repository.</li>
</ol>
<p>As usual, if you have questions then join the <a href="mailto:mongrel2@librelist.com">mongrel2@librelist.com</a> mailing list and we'll help out.</p>
|
