<!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>Developing Roundup &mdash; Roundup v1.4 documentation</title>
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '1.4',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Roundup v1.4 documentation" href="index.html" />
<link rel="next" title="Roundup Tracker Templates" href="tracker_templates.html" />
<link rel="prev" title="Roundup - An Issue-Tracking System for Knowledge Workers" href="design.html" />
</head>
<body>
<div class="header"><h1>Roundup</h1>
<div id="searchbox" style="display: none">
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
<div class="navigation">
<div class="menu">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Developing Roundup</a><ul>
<li><a class="reference external" href="#getting-started">Getting Started</a></li>
<li><a class="reference external" href="#website-wiki">Website, wiki</a></li>
<li><a class="reference external" href="#issue-tracker">Issue Tracker</a></li>
<li><a class="reference external" href="#small-changes">Small Changes</a></li>
<li><a class="reference external" href="#svn-access">SVN Access</a></li>
<li><a class="reference external" href="#project-rules">Project Rules</a></li>
<li><a class="reference external" href="#debugging-aids">Debugging Aids</a></li>
<li><a class="reference external" href="#internationalization-notes">Internationalization Notes</a><ul>
<li><a class="reference external" href="#gnu-gettext-package">GNU gettext package</a></li>
<li><a class="reference external" href="#marking-strings-for-translation">Marking Strings for Translation</a><ul>
<li><a class="reference external" href="#command-line-interfaces">Command Line Interfaces</a></li>
<li><a class="reference external" href="#deferred-translations">Deferred Translations</a></li>
<li><a class="reference external" href="#web-user-interface">Web User Interface</a></li>
</ul>
</li>
<li><a class="reference external" href="#extracting-translatable-messages">Extracting Translatable Messages</a></li>
<li><a class="reference external" href="#translating-messages">Translating Messages</a></li>
<li><a class="reference external" href="#compiling-message-catalogs">Compiling Message Catalogs</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="design.html"
title="previous chapter">Roundup - An Issue-Tracking System for Knowledge Workers</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tracker_templates.html"
title="next chapter">Roundup Tracker Templates</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/developers.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p style="font-size: 90%">Enter search terms or a module, class or function name.</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="content">
<div class="related related-top">
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="tracker_templates.html" title="Roundup Tracker Templates"
accesskey="N">next</a></li>
<li class="right" >
<a href="design.html" title="Roundup - An Issue-Tracking System for Knowledge Workers"
accesskey="P">previous</a></li>
<li><a href="index.html">Roundup v1.4 documentation</a></li>
</ul>
</div>
<div class="section" id="developing-roundup">
<h1><a class="toc-backref" href="#id2">Developing Roundup</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The intended audience of this document is the developers of the core
Roundup code. If you just wish to alter some behaviour of your Roundup
installation, see <a class="reference external" href="customizing.html">customising roundup</a>.</p>
</div>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#developing-roundup" id="id2">Developing Roundup</a><ul>
<li><a class="reference internal" href="#getting-started" id="id3">Getting Started</a></li>
<li><a class="reference internal" href="#website-wiki" id="id4">Website, wiki</a></li>
<li><a class="reference internal" href="#issue-tracker" id="id5">Issue Tracker</a></li>
<li><a class="reference internal" href="#small-changes" id="id6">Small Changes</a></li>
<li><a class="reference internal" href="#svn-access" id="id7">SVN Access</a></li>
<li><a class="reference internal" href="#project-rules" id="id8">Project Rules</a></li>
<li><a class="reference internal" href="#debugging-aids" id="id9">Debugging Aids</a></li>
<li><a class="reference internal" href="#internationalization-notes" id="id10">Internationalization Notes</a><ul>
<li><a class="reference internal" href="#gnu-gettext-package" id="id11">GNU gettext package</a></li>
<li><a class="reference internal" href="#marking-strings-for-translation" id="id12">Marking Strings for Translation</a><ul>
<li><a class="reference internal" href="#command-line-interfaces" id="id13">Command Line Interfaces</a></li>
<li><a class="reference internal" href="#deferred-translations" id="id14">Deferred Translations</a></li>
<li><a class="reference internal" href="#web-user-interface" id="id15">Web User Interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extracting-translatable-messages" id="id16">Extracting Translatable Messages</a></li>
<li><a class="reference internal" href="#translating-messages" id="id17">Translating Messages</a></li>
<li><a class="reference internal" href="#compiling-message-catalogs" id="id18">Compiling Message Catalogs</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="getting-started">
<h2><a class="toc-backref" href="#id3">Getting Started</a></h2>
<p>Anyone wishing to help in the development of Roundup must read <a class="reference external" href="spec.html">Roundup’s
Design Document</a> and the <a class="reference external" href="implementation.html">implementation notes</a>.</p>
<p>All development is coordinated through two resources:</p>
<ul class="simple">
<li>roundup-dev mailing list at
<a class="reference external" href="http://lists.sourceforge.net/mailman/listinfo/roundup-devel">http://lists.sourceforge.net/mailman/listinfo/roundup-devel</a></li>
<li>The issue tracker running at
<a class="reference external" href="http://issues.roundup-tracker.org/">http://issues.roundup-tracker.org/</a></li>
</ul>
</div>
<div class="section" id="website-wiki">
<h2><a class="toc-backref" href="#id4">Website, wiki</a></h2>
<ol class="arabic simple">
<li>ssh -t <username>,roundup@shell.sourceforge.net create</li>
<li>cd /home/groups/r/ro/roundup</li>
<li>follow instructions in README.txt</li>
</ol>
</div>
<div class="section" id="issue-tracker">
<h2><a class="toc-backref" href="#id5">Issue Tracker</a></h2>
<p>The tracker resides on psf.upfronthosting.co.za. The roundup installation
belongs to the user roundup. In ~roundup, all trackers are stored and
the roundup code itself. roundup is started through /etc/init.d/roundup;
other parts of the installation are started through
/etc/init.d/{postgresql-8-1,spambayes,postfix}.</p>
<p>The machine is operated by Upfronthosting in South Africa. The meta
tracker is <a class="reference external" href="http://psf.upfronthosting.co.za/roundup/meta/">http://psf.upfronthosting.co.za/roundup/meta/</a>
In this tracker, Upfronthosting people are the users izak and roche.</p>
<p>The Roundup tracker <a class="reference external" href="http://issues.roundup-tracker.org/">http://issues.roundup-tracker.org/</a> is in
~roundup/trackers/roundup</p>
<p>The configuration is in the “web/trunk/issues” section of Roundup’s
Subversion repository and copied manually to the live tracker.</p>
<p>A checkout of the roundup sources is in ~roundup/src/roundup-src.</p>
</div>
<div class="section" id="small-changes">
<h2><a class="toc-backref" href="#id6">Small Changes</a></h2>
<p>Most small changes can be submitted through the issue tracker, with
patches attached that give context diffs of the affected source.</p>
</div>
<div class="section" id="svn-access">
<h2><a class="toc-backref" href="#id7">SVN Access</a></h2>
<p>See <a class="reference external" href="http://www.roundup-tracker.org/code.html">http://www.roundup-tracker.org/code.html</a>.
For all other questions ask on the development mailinglist.</p>
</div>
<div class="section" id="project-rules">
<h2><a class="toc-backref" href="#id8">Project Rules</a></h2>
<p>Mostly the project follows Guido’s Style (though naming tends to be a little
relaxed sometimes). In short:</p>
<ul class="simple">
<li>80 column width code</li>
<li>4-space indentations</li>
<li>All modules must have an Id line near the top</li>
</ul>
<p>Other project rules:</p>
<ul class="simple">
<li>New functionality must be documented, even briefly (so at least we know
where there’s missing documentation) and changes to tracker configuration
must be logged in the upgrading document.</li>
<li>subscribe to roundup-checkins to receive checkin notifications from the
other developers with write access to the source-code repository.</li>
<li>discuss any changes with the other developers on roundup-dev. If nothing
else, this makes sure there’s no rude shocks</li>
<li>write unit tests for changes you make (where possible), and ensure that
all unit tests run before committing changes</li>
<li>run pychecker over changed code</li>
</ul>
<p>The administrators of the project reserve the right to boot developers who
consistently check in code which is either broken or takes the codebase in
directions that have not been agreed to.</p>
</div>
<div class="section" id="debugging-aids">
<h2><a class="toc-backref" href="#id9">Debugging Aids</a></h2>
<p>See <a href="#id19"><span class="problematic" id="id20">`debugging.txt`_</span></a>.</p>
</div>
<div class="section" id="internationalization-notes">
<h2><a class="toc-backref" href="#id10">Internationalization Notes</a></h2>
<p>How stuff works:</p>
<ol class="arabic simple">
<li>Strings that may require translation (messages in human language)
are marked in the source code. This step is discussed in
<a class="reference internal" href="#marking-strings-for-translation">Marking Strings for Translation</a> section.</li>
<li>These strings are all extracted into Message Template File
<tt class="docutils literal"><span class="pre">locale/roundup.pot</span></tt> (<span class="target" id="pot">POT</span> file). See <a class="reference internal" href="#extracting-translatable-messages">Extracting Translatable
Messages</a> below.</li>
<li>Language teams use POT file to make Message Files for national
languages (<span class="target" id="po">PO</span> files). All PO files for Roundup are kept in
the <tt class="docutils literal"><span class="pre">locale</span></tt> directory. Names of these files are target
locale names, usually just 2-letter language codes. <a class="reference internal" href="#translating-messages">Translating
Messages</a> section of this chapter gives useful hints for
message translators.</li>
<li>Translated Message Files are compiled into binary form (<span class="target" id="mo">MO</span> files)
and stored in <tt class="docutils literal"><span class="pre">locale</span></tt> directory (but not kept in the source code
repository, as they may be easily made from PO files).
See <a class="reference internal" href="#compiling-message-catalogs">Compiling Message Catalogs</a> section.</li>
<li>Roundup installer creates runtime locale structure on the file
system, putting MO files in their appropriate places.</li>
<li>Runtime internationalization (<span class="target" id="i18n">I18N</span>) services use these MO files
to translate program messages into language selected by current
Roundup user. Roundup command line interface uses locale name
set in OS environment variable <tt class="docutils literal"><span class="pre">LANGUAGE</span></tt>, <tt class="docutils literal"><span class="pre">LC_ALL</span></tt>,
<tt class="docutils literal"><span class="pre">LC_MESSAGES</span></tt>, or <tt class="docutils literal"><span class="pre">LANG</span></tt> (in that order). Roundup Web User
Interface uses language selected by currently authenticated user.</li>
</ol>
<p>Additional details may be found in <a class="reference internal" href="#gnu-gettext">GNU gettext</a> and Python <a class="reference external" href="http://docs.python.org/lib/module-gettext.html">gettext
module</a> documentation.</p>
<p><a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=31577">Roundup source distribution</a> includes POT and PO files for message
translators, and also pre-built MO files to facilitate installations
from source. Roundup binary distribution includes MO files only.</p>
<div class="section" id="gnu-gettext-package">
<span id="gnu-gettext"></span><h3><a class="toc-backref" href="#id11">GNU gettext package</a></h3>
<p>This chapter is full of references to GNU <a class="reference external" href="http://www.gnu.org/software/gettext/">gettext package</a>.
GNU gettext is a “must have” for nearly all steps of internationalizing
any program, and it’s manual is definetely a recommended reading
for people involved in <a class="reference internal" href="#i18n">I18N</a>.</p>
<p>There are GNU gettext ports to all major OS platforms.
Windows binaries are available from <a class="reference external" href="http://www.gnu.org/prep/ftp.html">GNU mirror sites</a>.</p>
<p>Roundup does not use GNU gettext at runtime, but it’s tools
are used for <a class="reference internal" href="#extracting-translatable-messages">extracting translatable messages</a>, <a class="reference internal" href="#compiling-message-catalogs">compiling
message catalogs</a> and, optionally, for <a class="reference internal" href="#translating-messages">translating messages</a>.</p>
<p>Note that <tt class="docutils literal"><span class="pre">gettext</span></tt> package in some OS distributions means just
runtime tools and libraries. In such cases gettext development tools
are usually distributed in separate package named <tt class="docutils literal"><span class="pre">gettext-devel</span></tt>.</p>
</div>
<div class="section" id="marking-strings-for-translation">
<h3><a class="toc-backref" href="#id12">Marking Strings for Translation</a></h3>
<p>Strings that need translation must be marked in the source code.
Following subsections explain how this is done in different cases.</p>
<p>If translatable string is used as a format string, it is recommended
to always use <em>named</em> format specifiers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">_</span><span class="p">(</span><span class="s">'Index of </span><span class="si">%(classname)s</span><span class="s">'</span><span class="p">)</span> <span class="o">%</span> <span class="nb">locals</span><span class="p">()</span>
</pre></div>
</div>
<p>This helps translators to better understand the context of the
message and, with Python formatting, remove format specifier altogether
(which is sometimes useful, especially in singular cases of <a class="reference external" href="http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html">Plural Forms</a>).</p>
<p>When there is more than one format specifier in the translatable
format string, named format specifiers <strong>must</strong> be used almost always,
because translation may require different order of items.</p>
<p>It is better to <em>not</em> mark for translation strings that are not
locale-dependent, as this makes it more difficult to keep track
of translation completeness. For example, string <tt class="docutils literal"><span class="pre"></ol></body></html></span></tt>
(in <tt class="docutils literal"><span class="pre">index()</span></tt> method of the request handler in <tt class="docutils literal"><span class="pre">roundup_server</span></tt>
script) has no human readable parts at all, and needs no translations.
Such strings are left untranslated in PO files, and are reported
as such by PO status checkers (e.g. <tt class="docutils literal"><span class="pre">msgfmt</span> <span class="pre">--statistics</span></tt>).</p>
<div class="section" id="command-line-interfaces">
<h4><a class="toc-backref" href="#id13">Command Line Interfaces</a></h4>
<p>Scripts and routines run from the command line use “static” language
defined by environment variables recognized by <tt class="docutils literal"><span class="pre">gettext</span></tt> module
from Python library (<tt class="docutils literal"><span class="pre">LANGUAGE</span></tt>, <tt class="docutils literal"><span class="pre">LC_ALL</span></tt>, <tt class="docutils literal"><span class="pre">LC_MESSAGES</span></tt>, and
<tt class="docutils literal"><span class="pre">LANG</span></tt>). Primarilly, these are <tt class="docutils literal"><span class="pre">roundup-admin</span></tt> script and
<tt class="docutils literal"><span class="pre">admin.py</span></tt> module, but also help texts and startup error messages
in other scripts and their supporting modules.</p>
<p>For these interfaces, Python <tt class="docutils literal"><span class="pre">gettext</span></tt> engine must be initialized
to use Roundup message catalogs. This is normally done by including
the following line in the module imports:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">i18n</span> <span class="kn">import</span> <span class="n">_</span><span class="p">,</span> <span class="n">ngettext</span>
</pre></div>
</div>
<p>Simple translations are automatically marked by calls to builtin
message translation function <tt class="docutils literal"><span class="pre">_()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">_</span><span class="p">(</span><span class="s">"This message is translated"</span><span class="p">)</span>
</pre></div>
</div>
<p>Translations for messages whose grammatical depends on a number
must be done by <tt class="docutils literal"><span class="pre">ngettext()</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">ngettext</span><span class="p">(</span><span class="s">"Nuked </span><span class="si">%i</span><span class="s"> file"</span><span class="p">,</span> <span class="s">"Nuked </span><span class="si">%i</span><span class="s"> files"</span><span class="p">,</span> <span class="n">number_of_files_nuked</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="deferred-translations">
<h4><a class="toc-backref" href="#id14">Deferred Translations</a></h4>
<p>Sometimes translatable strings appear in the source code in untranslated
form <a class="footnote-reference" href="#note-admin-py" id="id1">[1]</a> and must be translated elsewhere.
Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">meal</span> <span class="ow">in</span> <span class="p">(</span><span class="s">"spam"</span><span class="p">,</span> <span class="s">"egg"</span><span class="p">,</span> <span class="s">"beacon"</span><span class="p">):</span>
<span class="k">print</span> <span class="n">_</span><span class="p">(</span><span class="n">meal</span><span class="p">)</span>
</pre></div>
</div>
<p>In such cases, strings must be marked for translation without actual
call to the translating function. To mark these strings, we use Python
feature of automatic concatenation of adjacent strings and different
types of string quotes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">strings_to_translate</span> <span class="o">=</span> <span class="p">(</span>
<span class="s">''"This string will be translated"</span><span class="p">,</span>
<span class="s">""'me too'</span><span class="p">,</span>
<span class="s">''r"\raw string"</span><span class="p">,</span>
<span class="s">''"""</span>
<span class="s"> multiline string"""</span>
<span class="p">)</span>
</pre></div>
</div>
<table class="docutils footnote" frame="void" id="note-admin-py" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>In current Roundup sources, this feature is
extensively used in the <tt class="docutils literal"><span class="pre">admin</span></tt> module using method docstrings
as help messages.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="web-user-interface">
<h4><a class="toc-backref" href="#id15">Web User Interface</a></h4>
<p>For Web User Interface, translation services are provided by Client
object. Action classes have methods <tt class="docutils literal"><span class="pre">_()</span></tt> and <tt class="docutils literal"><span class="pre">gettext()</span></tt>,
delegating translation to the Client instance. In HTML templates,
translator object is available as context variable <tt class="docutils literal"><span class="pre">i18n</span></tt>.</p>
<p>HTML templates have special markup for translatable strings.
The syntax for this markup is defined on <a class="reference external" href="http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport">ZPTInternationalizationSupport</a>
page. Roundup translation service currently ignores values for
<tt class="docutils literal"><span class="pre">i18n:domain</span></tt>, <tt class="docutils literal"><span class="pre">i18n:source</span></tt> and <tt class="docutils literal"><span class="pre">i18n:target</span></tt>.</p>
<p>Template markup examples:</p>
<ul>
<li><p class="first">simplest case:</p>
<div class="highlight-python"><pre><div i18n:translate="">
Say
no
more!
</div></pre>
</div>
<p>this will result in msgid <tt class="docutils literal"><span class="pre">"Say</span> <span class="pre">no</span> <span class="pre">more!"</span></tt>, with all leading and
trailing whitespace stripped, and inner blanks replaced with single
space character.</p>
</li>
<li><p class="first">using variable slots:</p>
<div class="highlight-python"><pre><div i18n:translate="">
And now...<br/>
No.<span tal:replace="number" i18n:name="slideNo" /><br/>
THE LARCH
</div></pre>
</div>
<p>Msgid will be: <tt class="docutils literal"><span class="pre">"And</span> <span class="pre">now...<br</span> <span class="pre">/></span> <span class="pre">No.${slideNo}<br</span> <span class="pre">/></span> <span class="pre">THE</span> <span class="pre">LARCH"</span></tt>.
Template rendering will use context variable <tt class="docutils literal"><span class="pre">number</span></tt> (you may use
any expression) to put instead of <tt class="docutils literal"><span class="pre">${slideNo}</span></tt> in translation.</p>
</li>
<li><p class="first">attribute translation:</p>
<div class="highlight-python"><pre><button name="btn_wink" value=" Wink " i18n:attributes="value" /></pre>
</div>
<p>will translate the caption (and return value) for the “wink” button.</p>
</li>
<li><p class="first">explicit msgids. Sometimes it may be useful to specify msgid
for the element translation explicitely, like this:</p>
<div class="highlight-python"><pre><span i18n:translate="know what i mean?">this text is ignored</span></pre>
</div>
<p>When rendered, element contents will be replaced by translation
of the string specified in <tt class="docutils literal"><span class="pre">i18n:translate</span></tt> attribute.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">i18n</span></tt> in <a class="reference external" href="http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3">TALES</a>. You may translate strings in <a class="reference external" href="http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3">TALES</a> python
expressions:</p>
<div class="highlight-python"><pre><span tal:replace="python: i18n.gettext('Oh, wicked.')" /></pre>
</div>
</li>
<li><p class="first">plural forms. There is no markup for plural forms in <a class="reference external" href="http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4">TAL</a> i18n.
You must use python expression for that:</p>
<div class="highlight-python"><pre><span tal:replace="python: i18n.ngettext(
'Oh but it\'s only %i shilling.',
'Oh but it\'s only %i shillings.',
fine) % fine"
/></pre>
</div>
</li>
</ul>
</div>
</div>
<div class="section" id="extracting-translatable-messages">
<h3><a class="toc-backref" href="#id16">Extracting Translatable Messages</a></h3>
<p>The most common tool for message extraction is <tt class="docutils literal"><span class="pre">xgettext</span></tt> utility
from <a class="reference internal" href="#gnu-gettext-package">GNU gettext package</a>. Unfortunately, this utility has no means
of <a class="reference internal" href="#deferred-translations">Deferred Translations</a> in Python sources. There is <tt class="docutils literal"><span class="pre">xpot</span></tt> tool
from Francois Pinard free <a class="reference external" href="http://po-utils.progiciels-bpi.ca/">PO utilities</a> that allows to mark strings
for deferred translations, but it does not handle <a class="reference external" href="http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html">plural forms</a>.</p>
<p>Roundup overcomes these limitations by using both of these utilities.
This means that you need both <a class="reference internal" href="#gnu-gettext">GNU gettext</a> tools and <a class="reference external" href="http://po-utils.progiciels-bpi.ca/">PO utilities</a>
to build the Message Template File yourself.</p>
<p>Latest Message Template File is kept in the source code repository
and distributed with <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=31577">Roundup Source</a>.
If you wish to rebuild the template yourself,
make sure that you have both <tt class="docutils literal"><span class="pre">xpot</span></tt> and <tt class="docutils literal"><span class="pre">xgettext</span></tt> installed and
just run <tt class="docutils literal"><span class="pre">gmake</span></tt> (or <tt class="docutils literal"><span class="pre">make</span></tt>, if you are on a <a class="reference external" href="http://www.gnu.org/">GNU</a> system like
<a class="reference external" href="http://www.linux.org/">linux</a> or <a class="reference external" href="http://www.cygwin.com/">cygwin</a>) in the <tt class="docutils literal"><span class="pre">locale</span></tt> directory.</p>
<p>For on-site i18n, Roundup provides command-line utility:</p>
<div class="highlight-python"><pre>roundup-gettext <tracker_home></pre>
</div>
<p>extracting translatable messages from tracker’s html templates.
This utility creates message template file <tt class="docutils literal"><span class="pre">messages.pot</span></tt> in
<tt class="docutils literal"><span class="pre">locale</span></tt> subdirectory of the tracker home directory. Translated
messages may be put in <em>locale</em>.po files (where <em>locale</em> is selected
locale name) in the same directory, e.g.: <tt class="docutils literal"><span class="pre">locale/ru.po</span></tt>.
These message catalogs are searched prior to system-wide translations
kept in the <tt class="docutils literal"><span class="pre">share</span></tt> directory.</p>
</div>
<div class="section" id="translating-messages">
<h3><a class="toc-backref" href="#id17">Translating Messages</a></h3>
<p>Gettext Message File (<a class="reference internal" href="#po">PO</a> file) is a plain text file, that can be created
by simple copying <tt class="docutils literal"><span class="pre">roundup.pot</span></tt> to new .po file, like this:</p>
<div class="highlight-python"><pre>$ cp roundup.pot ru.po</pre>
</div>
<p>The name of PO file is target locale name, usually just 2-letter language
code (<tt class="docutils literal"><span class="pre">ru</span></tt> for Russian in the above example). Alternatively, PO file
may be initialized by <tt class="docutils literal"><span class="pre">msginit</span></tt> utility from <a class="reference internal" href="#gnu-gettext">GNU gettext</a> tools:</p>
<div class="highlight-python"><pre>$ msginit -i roundup.pot</pre>
</div>
<p><tt class="docutils literal"><span class="pre">msginit</span></tt> will check your current locale, and initialize the header
entry, setting language name, rules for <a class="reference external" href="http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html">plural forms</a> and, if available,
translator’s name and email address. The name for PO file is also chosen
based on current locale.</p>
<p>Next, you will need to edit this file, filling all <tt class="docutils literal"><span class="pre">msgstr</span></tt> lines with
translations of the above <tt class="docutils literal"><span class="pre">msgid</span></tt> entries. PO file is a plain text
file that can be edited with any text editor. However, there are several
tools that may help you with this process:</p>
<blockquote>
<ul>
<li><p class="first"><a class="reference external" href="http://poedit.sourceforge.net/">poEdit</a> by Vaclav Slavik. Very nice cross-platform GUI editor.</p>
</li>
<li><dl class="first docutils">
<dt><a class="reference external" href="http://i18n.kde.org/tools/kbabel/">KBabel</a>. Being part of <a class="reference external" href="http://www.kde.org/">KDE</a>, it works in X windows only.</dt>
<dd><p class="first last">At the first glance looks pretty hairy, with all bells and whistles.
Haven’t had much experience with it, though.</p>
</dd>
</dl>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">po-mode</span></tt> for <a class="reference external" href="http://www.gnu.org/software/emacs/">emacs</a>. One of <a class="reference internal" href="#gnu-gettext">GNU gettext</a> tools. Very handy,
definitely recommended if you are comfortable with emacs. Cannot
handle <a class="reference external" href="http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html">plural forms</a> per se, but allows to edit them in simple
text mode.</p>
</li>
<li><p class="first"><a class="reference external" href="http://vim.sourceforge.net/scripts/script.php?script_id=695">po filetype plugin</a> for <a class="reference external" href="http://www.vim.org/">vim</a>. Does not do as much as <tt class="docutils literal"><span class="pre">po-mode</span></tt>,
but helps in finding untranslated and fuzzy strings, and checking
code references. Please contact <a class="reference external" href="http://sourceforge.net/users/a1s/">alexander smishlajev</a> if you
prefer this, as i have patched this plugin a bit. I have also
informed the original plugin author about these changes, but got
no reply so far.</p>
</li>
</ul>
</blockquote>
</div>
<div class="section" id="compiling-message-catalogs">
<h3><a class="toc-backref" href="#id18">Compiling Message Catalogs</a></h3>
<p>Message catalogs (<a class="reference internal" href="#po">PO</a> files) must be compiled into binary form
(<a class="reference internal" href="#mo">MO</a> files) before they can be used in the application. This
compilation is handled by <tt class="docutils literal"><span class="pre">msgfmt</span></tt> utility from <a class="reference internal" href="#gnu-gettext">GNU gettext</a>
tools. <tt class="docutils literal"><span class="pre">GNUmakefile</span></tt> in the <tt class="docutils literal"><span class="pre">locale</span></tt> directory automatically
compiles all existing message catalogs after updating them from
Roundup source files. If you wish to rebuild an individual <a class="reference internal" href="#mo">MO</a>
file without making everything else, you may, for example:</p>
<div class="highlight-python"><pre>$ msgfmt --statistics -o ru.mo ru.po</pre>
</div>
<p>This way, message translators can check their <a class="reference internal" href="#po">PO</a> files without
extracting strings from source. (Note: String extraction requires
additional utility that is not part of <a class="reference internal" href="#gnu-gettext">GNU gettext</a>. See <a class="reference internal" href="#extracting-translatable-messages">Extracting
Translatable Messages</a>.)</p>
<p>At run time, Roundup automatically compiles message catalogs whenever
<a class="reference internal" href="#po">PO</a> file is changed.</p>
</div>
</div>
</div>
<div class="related related-bottom">
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="tracker_templates.html" title="Roundup Tracker Templates"
accesskey="N">next</a></li>
<li class="right" >
<a href="design.html" title="Roundup - An Issue-Tracking System for Knowledge Workers"
accesskey="P">previous</a></li>
<li><a href="index.html">Roundup v1.4 documentation</a></li>
</ul>
</div>
</div>
<div class="footer">
© Copyright 2009, Richard Jones.
<p class="source"><a href="_sources/developers.txt" rel="nofollow">source</a></p>
</div>
</body>
</html>
