Menu
▾
▴
[Roundup-checkins] [PATCH 1 of 6] doc: reorder sections, roundup-gettext doc; jinja2 message extraction
|
From: Mercurial C. <th...@in...> - 2026-05-17 06:27:51
|
# HG changeset patch
# User John Rouillard <ro...@ie...>
# Date 1778692110 14400
# Wed May 13 13:08:30 2026 -0400
# Node ID 3f76baa4f0cb477c42e59aa09f9826465bdd4665
# Parent 1352ae565dee514bfbf2631e56ac8c047ffd9700
doc: reorder sections, roundup-gettext doc; jinja2 message extraction
Moved a number of sections around to group by:
marking translations
extracting translations
translating translations
Moved using translations in CLI to end from the middle of the other
structure as it didn't fit there.
Replaced footnote on roundup-gettext limitations with paragraph and
added lack of support for .Hint notes.
Added reference to jinja-i18n-tools for extracting translatable
strings from jinja templates. I wasn't able to run it successfully on
our jinja template though. But I was able to get pybabel to work so I
documented that.
diff -r 1352ae565dee -r 3f76baa4f0cb doc/developers.txt
--- a/doc/developers.txt Mon May 11 13:31:02 2026 -0400
+++ b/doc/developers.txt Wed May 13 13:08:30 2026 -0400
@@ -372,34 +372,8 @@
allowing the translator to see the replaced string so they can
understand how name and value are used.
-Command Line Interfaces
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Scripts and routines run from the command line use "static" language
-defined by environment variables recognized by ``gettext`` module
-from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
-``LANG``). Primarily, these are ``roundup-admin`` script and
-``admin.py`` module, but also help texts and startup error messages
-in other scripts and their supporting modules.
-
-For these interfaces, Python ``gettext`` engine must be initialized
-to use Roundup message catalogs. This is normally done by including
-the following line in the module imports::
-
- from i18n import _, ngettext
-
-Simple translations are automatically marked by calls to builtin
-message translation function ``_()``::
-
- print(_("This message is translated"))
-
-Translations for messages whose grammatical depends on a number
-must be done by ``ngettext()`` function::
-
- print(ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked))
-
Deferred Translations
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
Sometimes translatable strings appear in the source code in untranslated
form [#note_admin.py]_ and must be translated elsewhere.
@@ -426,7 +400,7 @@
as help messages.
Web User Interface
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
For Web User Interface, translation services are provided by Client
object. Action classes have methods ``_()`` and ``gettext()``,
@@ -516,7 +490,7 @@
see: localization; i18n
Extracting Translatable Messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The most common tool for message extraction is ``xgettext`` utility
from `GNU gettext package`_. Unfortunately, this utility has no means
@@ -535,12 +509,15 @@
just run ``gmake`` (or ``make``, if you are on a `GNU`_ system like
`linux`_ or `cygwin`_) in the ``locale`` directory.
+On-site Tracker Translation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
For on-site i18n, Roundup provides command-line utility::
roundup-gettext <tracker_home>
extracting translatable messages from tracker's html templates and
-detectors / extensions (assuming `polib`_ is installed) [2]_.
+detectors / extensions (assuming `polib`_ is installed).
This utility creates message template file ``messages.pot`` in
``locale`` subdirectory of the tracker home directory. Translated
messages may be put in *locale*.po files (where *locale* is the two
@@ -548,6 +525,34 @@
These message catalogs are searched prior to system-wide translations
kept in the ``share`` directory.
+Note that ``roundup-gettext`` only works with trackers using TAL based
+templates. Also it does not support the markup used for deferred
+translations. Deferred translation strings have to be manually added
+to messages.pot. It also does not support hint comments.
+
+If you are using a jinja2 based template, it looks like the
+`jinja-i18n-tools`_ package might be helpful. It can be installed
+using ``pip``.
+
+After creating the ```locale`` subdirectory in my tracker home, I was
+able to use::
+
+ pybabel extract -F babel.cfg -d locale --add-comments ".Hint' \
+ --output locale/messages.po .
+
+with the following ``babel.cfg``::
+
+ [python: **.py]
+ [jinja2: html/**.html]
+ extensions=jinja2.ext.i18n
+
+Note that extracting deferred translations using a concatenated empty
+string does not seem to work.
+
+If you are successful at using local translations with your jinja2
+template based tracker, please contact the Roundup authors (see
+Contact on the main web page) so we can add more detailed directions.
+
If you are creating your own ``.po`` file from scratch rather than
using ``roundup-gettext``, you must have the minimal preamble
specifying the format of the file. This::
@@ -562,12 +567,9 @@
of the ASCII range will cause Roundup to crash with a
UnicodeDecodeError.
-.. [2] Note that it will not extract `deferred translations`_
- from detectors or extensions. Those have to be manually
- added to messages.pot.
Translating Messages
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
Gettext Message File (`PO`_ file) is a plain text file, that can be created
by simple copying ``roundup.pot`` to new .po file, like this::
@@ -633,6 +635,31 @@
.. [1] Roundup is written in Python and we believe in using tools in
the Python ecosystem whenever possible.
+Command Line Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Scripts and routines run from the command line use "static" language
+defined by environment variables recognized by ``gettext`` module
+from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
+``LANG``). Primarily, these are ``roundup-admin`` script and
+``admin.py`` module, but also help texts and startup error messages
+in other scripts and their supporting modules.
+
+For these interfaces, Python ``gettext`` engine must be initialized
+to use Roundup message catalogs. This is normally done by including
+the following line in the module imports::
+
+ from i18n import _, ngettext
+
+Simple translations are automatically marked by calls to builtin
+message translation function ``_()``::
+
+ print(_("This message is translated"))
+
+Translations for messages whose grammatical depends on a number
+must be done by ``ngettext()`` function::
+
+ print(ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked))
.. _`Customising Roundup`: customizing.html
@@ -660,6 +687,7 @@
.. _hosted at sourceforge:
https://sourceforge.net/p/roundup/code/ci/default/tree/
.. _issue tracker: https://issues.roundup-tracker.org/
+.. _jinja-i18n-tools: https://pypi.org/project/jinja-i18n-tools/-i
.. _Lokalize: https://apps.kde.org/lokalize/
.. _KDE: https://kde.org/
.. _linux: https://www.linux.org/
|