summaryrefslogtreecommitdiffstats
path: root/files/manual.chunked/ar01s08.html
blob: 5830c1a2c94a8037598649f5c6ddcd19463a939e (plain) (blame)
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8. How to contribute?</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /><link rel="home" href="index.html" title="CALCURSE - text-based organizer" /><link rel="up" href="index.html" title="CALCURSE - text-based organizer" /><link rel="prev" href="ar01s07.html" title="7. Reporting bugs and feedback" /><link rel="next" href="ar01s09.html" title="9. Links" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ar01s07.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s09.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contribute"></a>8. How to contribute?</h2></div></div></div><p>If you would like to contribute to the project, you can first send your
feedback on what you like or dislike, and if there are features you miss in
<code class="literal">calcurse</code>.  For now on, possible contributions concern the translation of
<code class="literal">calcurse</code> messages and documentation.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_translating_documentation"></a>8.1. Translating documentation</h3></div></div></div><div class="note" style="margin-left: 0; margin-right: 10%;"><h3 class="title">Note</h3><p>We recently dropped all translations of the manual files from the
      distribution tarball. There are plan to reintroduce them in form of a
      Wiki on the calcurse website. Please follow the mailing lists for
      up-to-date information.</p></div><p>The <span class="strong"><strong>doc/</strong></span> directory of the source package already contains translated version
of <code class="literal">calcurse</code> manual. However, if the manual is not yet available into your
native language, it would be appreciated if you could help translating it.</p><p>To do so, just copy one of the existing manual file to <code class="literal">manual_XX.html</code>, where
<span class="strong"><strong>XX</strong></span> identifies your language. Then translate this newly created file and send
it to the author (see <a class="link" href="ar01s07.html" title="7. Reporting bugs and feedback">Reporting bugs and feeback</a>), so that it can be
included in the next <code class="literal">calcurse</code> release.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_calcurse_i18n"></a>8.2. calcurse i18n</h3></div></div></div><p>As already mentioned, <code class="literal">gettext</code> utilities are used by <code class="literal">calcurse</code> to produce
multi-lingual messages. We are currently using
<a class="ulink" href="http://www.transifex.net/" target="_top">Transifex</a> to manage those translations.</p><p>This section provides informations about how to translate those messages into
your native language. However, this howto is deliberately incomplete, focusing
on working with <code class="literal">gettext</code> for <code class="literal">calcurse</code> specifically.  For more comprehensive
informations or to grasp the Big Picture of Native Language Support, you should
refer to the <code class="literal">GNU gettext</code> manual at:
<a class="ulink" href="http://www.gnu.org/software/gettext/manual/" target="_top">http://www.gnu.org/software/gettext/manual/</a></p><div class="important" style="margin-left: 0; margin-right: 10%;"><h3 class="title">Important</h3><p>Since we switched to Transifex, editing <span class="strong"><strong>po</strong></span> files is not necessary
           anymore as Transifex provides a user-friendly, intuitive web
           interface for translators. Knowledge of <code class="literal">gettext</code> and the <span class="strong"><strong>po</strong></span>
           format is still useful for those of you who prefer the command line
           and local editing. If you want to use the web UI to edit the
           translation strings, you can skip over to <a class="link" href="ar01s08.html#transifex_webui" title="Using the Transifex web UI">Using            the Transifex web UI</a> tough.</p></div><p>Basically, three different people get involved in the translation chain:
coders, language coordinator, and translators. After a quick overview of how
things work, the translator tasks will be described hereafter.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_overview_2"></a>Overview</h4></div></div></div><p>To be able to display texts in the native language of the user, two steps are
required: <span class="strong"><strong>internationalization</strong></span> (i18n) and <span class="strong"><strong>localization</strong></span> (l10n).</p><p>i18n is about making <code class="literal">calcurse</code> support multiple languages. It is performed by
coders, who will mark translatable texts and provide a way to display them
translated at runtime.</p><p>l10n is about making the i18n’ed <code class="literal">calcurse</code> adapt to the specific language of
the user, ie translating the strings previously marked by the developers, and
setting the environment correctly for <code class="literal">calcurse</code> to use the result of this
translation.</p><p>So, translatable strings are first marked by the coders within the <code class="literal">C</code> source
files, then gathered in a template file (<span class="strong"><strong>calcurse.pot</strong></span> - the <span class="strong"><strong>pot</strong></span> extension
meaning <span class="strong"><strong>portable object template</strong></span>). The content of this template file is then
merged with the translation files for each language (<span class="strong"><strong>fr.po</strong></span> for French, for
instance - with <span class="strong"><strong>po</strong></span> standing for <span class="strong"><strong>portable object</strong></span>, ie meant to be read and
edited by humans). A given translation team will take this file, translate its
strings, and send it back to the developers. At compilation time, a binary
version of this file (for efficiency reasons) will be produced (<span class="strong"><strong>fr.mo</strong></span> - <span class="strong"><strong>mo</strong></span>
stands for <span class="strong"><strong>machine object</strong></span>, i.e. meant to be read by programs), and then
installed.  Then <code class="literal">calcurse</code> will use this file at runtime, translating the
strings according to the locale settings of the user.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_translator_tasks"></a>Translator tasks</h4></div></div></div><p>Suppose someone wants to initiate the translation of a new language. Here are
the steps to follow:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
First, find out what the locale name is. For instance, for french, it is
  <code class="literal">fr_FR</code>, or simply <code class="literal">fr</code>. This is the value the user will have to put in his
  <code class="literal">LC_ALL</code> environment variable for software to be translated (see
  <a class="link" href="ar01s04.html#basics_invocation_variable" title="Environment variable for i18n">Environment variable for i18n</a>).
</li><li class="listitem">
Then, go into the <span class="strong"><strong>po/</strong></span> directory, and create a new po-file
  from the template file using the following command: <code class="literal">msginit -i calcurse.pot
  -o fr.po -l fr --no-translator</code> If you do not have <code class="literal">msginit</code> installed on
  your system, simply copy the <span class="strong"><strong>calcurse.pot</strong></span> file to <span class="strong"><strong>fr.po</strong></span> and edit the
  header by hand.
</li></ul></div><p>Now, having this <span class="strong"><strong>fr.po</strong></span> file, the translator is ready to begin.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_po_files"></a>po-files</h4></div></div></div><p>The format of the po-files is quite simple. Indeed, po-files are made of four
things:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<span class="strong"><strong>location lines:</strong></span> tells you where the strings can be seen (name of file and
   line number), in case you need to see a bit of context.
</li><li class="listitem">
<span class="strong"><strong>msgid lines:</strong></span> the strings to translate.
</li><li class="listitem">
<span class="strong"><strong>msgstr lines:</strong></span> the translated strings.
</li><li class="listitem">
<span class="strong"><strong>lines prefixed with <code class="literal">#</code>:</strong></span> comments (some with a special meaning, as we will
   see below).
</li></ol></div><p>Basically, all you have to do is fill the <span class="strong"><strong>msgstr</strong></span> lines with the translation
of the above <span class="strong"><strong>msgid</strong></span> line.</p><p>A few notes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<span class="strong"><strong>Fuzzy strings</strong></span>
</span></dt><dd>
  You will meet strings marked with a <code class="literal">"#, fuzzy"</code> comment. <code class="literal">calcurse</code> won’t
  use the translations of such strings until you do something about them.  A
  string being fuzzy means either that the string has already been translated
  but has since been changed in the sources of the program, or that this is a
  new string for which <code class="literal">gettext</code> made a <span class="emphasis"><em>wild guess</em></span> for the translation, based
  on other strings in the file.  It means you have to review the translation.
  Sometimes, the original string has changed just because a typo has been
  fixed. In this case, you won’t have to change anything. But sometimes, the
  translation will no longer be accurate and needs to be changed.  Once you are
  done and happy with the translation, just remove the <code class="literal">"#, fuzzy"</code> line, and
  the translation will be used again in <code class="literal">calcurse</code>.
</dd><dt><span class="term">
<span class="strong"><strong>c-format strings and special sequences</strong></span>
</span></dt><dd>
  Some strings have the following comment: <code class="literal">"#, c-format"</code>.  This tells that
  parts of the string to translate have a special meaning for the program, and
  that you should leave them alone.  For instance, %-sequences, like <code class="literal">"%s"</code>.
  These means that <code class="literal">calcurse</code> will replace them with another string. So it is
  important it remains.  There are also \-sequences, like <code class="literal">\n</code> or <code class="literal">\t</code>. Leave
  them, too. The former represents an end of line, the latter a tabulation.
</dd><dt><span class="term">
<span class="strong"><strong>Translations can be wrapped</strong></span>
</span></dt><dd><p class="simpara">
  If lines are too long, you can just break them like this:
</p><pre class="screen">msgid ""
"some very long line"
"another line"</pre></dd><dt><span class="term">
<span class="strong"><strong>po-file header</strong></span>
</span></dt><dd><p class="simpara">
  At the very beginning of the po-file, the first string form a header, where
  various kind of information has to be filled in. Most important one is the
  charset. It should resemble
</p><pre class="screen">"Content-Type: text/plain; charset=utf-8\n"</pre><p class="simpara">You should also fill in the Last-Translator field, so that potential
contributors can contact you if they want to join you in the translation team,
or have remarks/typo fixes to give about the translations. You can either just
give your name/nick, or add an email address, for exemple:</p><pre class="screen">"Last-Translator: Frederic Culot &lt;frederic@culot.org&gt;\n"</pre></dd><dt><span class="term">
<span class="strong"><strong>Comments</strong></span>
</span></dt><dd>
  Adding comments (lines begining with the <code class="literal">#</code> character) can be a good way to
  point out problems or translation difficulties to proofreaders or other
  members of your team.
</dd><dt><span class="term">
<span class="strong"><strong>Strings size</strong></span>
</span></dt><dd>
  <code class="literal">calcurse</code> is a curses/console program, thus it can be heavily dependant on
  the terminal size (number of columns). You should think about this when
  translating. Often, a string must fit into a single line (standard length is
  80 characters). Don’t translate blindly, try to look where your string will
  be displayed to adapt your translation.
</dd><dt><span class="term">
<span class="strong"><strong>A few useful tools</strong></span>
</span></dt><dd><p class="simpara">
  The po-file format is very simple, and the file can be edited with a standard
  text editor.  But if you prefer, there are few specialized tools you may find
  convenient for translating:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<code class="literal">poEdit</code> (<a class="ulink" href="http://www.poedit.org/" target="_top">http://www.poedit.org/</a>)
</li><li class="listitem">
<code class="literal">KBabel</code> (<a class="ulink" href="http://i18n.kde.org/tools/kbabel/" target="_top">http://i18n.kde.org/tools/kbabel/</a>)
</li><li class="listitem">
<code class="literal">GTranslator</code> (<a class="ulink" href="http://gtranslator.sourceforge.net/" target="_top">http://gtranslator.sourceforge.net/</a>)
</li><li class="listitem">
<code class="literal">Emacs</code> po mode
</li><li class="listitem">
<code class="literal">Vim</code> po mode
</li></ul></div></dd><dt><span class="term">
<span class="strong"><strong>And finally</strong></span>
</span></dt><dd>
  I hope you’ll have fun contributing to a more internationalized world. :) If
  you have any more questions, don’t hesitate to contact us at <span class="strong"><strong>misc .at.
  calcurse .dot. org</strong></span>.
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="transifex_uploading"></a>Uploading to Transifex</h4></div></div></div><p>There’s several different ways to upload a finished (or semi-finished)
translation for a new language to Transifex. The easiest way is to browse to
the <a class="ulink" href="http://www.transifex.net/projects/p/calcurse/teams/" target="_top">Translation Teams</a> page
and request the addition of a new team.</p><p>As soon as we accepted your request, you will be able to upload your <span class="strong"><strong>po</strong></span> file
on the
<a class="ulink" href="http://www.transifex.net/projects/p/calcurse/resource/calcursepot/" target="_top">calcurse
resource page</a> by clicking the <span class="strong"><strong>Add translation</strong></span> button at the bottom.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_using_transifex_client"></a>Using transifex-client</h4></div></div></div><p>You can also use a command line client to submit translations instead of having
to use the web interface every time you want to submit an updated version. If
you have a recent version of <code class="literal">setuptools</code> installed, you can get the CLI client
by issuing the following command:</p><pre class="screen">$ easy_install -U transifex-client</pre><p>Alternatively, you can get the source code of transifex-client at
<a class="ulink" href="http://pypi.python.org/pypi/transifex-client" target="_top">http://pypi.python.org/pypi/transifex-client</a>.</p><p>After you downloaded and installed the client, run the following commands in
the calcurse source directory to checkout the translation resources of
<span class="strong"><strong>calcurse</strong></span>:</p><pre class="screen">$ tx pull -a</pre><p>To submit changes back to the server, use:</p><pre class="screen">$ tx push -r calcurse.calcursepot -t -l &lt;locale&gt;</pre><p>For more details, read up on <code class="literal">transifex-client</code> usage at the
<a class="ulink" href="http://help.transifex.net/user-guide/client/" target="_top">The Transifex Command-line Client
v0.4</a> section of the <a class="ulink" href="http://help.transifex.net/" target="_top">Transifex documentation</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="transifex_webui"></a>Using the Transifex web UI</h4></div></div></div><p>As an alternative to editing <span class="strong"><strong>po</strong></span> files, there is a web-based interface that
can be used to create and update translations. After having signed up and
created a new translation team (see <a class="link" href="ar01s08.html#transifex_uploading" title="Uploading to Transifex">Uploading to Transifex</a> on how to do that), click the <span class="strong"><strong>Add translation</strong></span> button at the
bottom on the
<a class="ulink" href="http://www.transifex.net/projects/p/calcurse/resource/calcursepot/" target="_top">calcurse
resource page</a>, select the language you’d like to translate and choose
<span class="strong"><strong>Translate Online</strong></span>.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s07.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>