|
1 | | -================================== |
2 | | -Roundup Internationalization Notes |
3 | | -================================== |
4 | | - |
5 | | -:Version: $Revision: 1.8 $ |
6 | | - |
7 | | -Overview |
8 | | --------- |
9 | | - |
10 | | -How stuff works: |
11 | | - |
12 | | -1. Strings that may require translation (messages in human language) |
13 | | - are marked in the source code. This step is discussed in |
14 | | - `Marking Strings for Translation`_ section. |
15 | | - |
16 | | -2. These strings are all extracted into Message Template File |
17 | | - ``locale/roundup.pot`` (POT file). See `Extracting Translatable |
18 | | - Messages`_ below. |
19 | | - |
20 | | -3. Language teams use POT file to make Message Files for national |
21 | | - languages (PO files). All PO files for Roundup are kept in |
22 | | - the ``locale`` directory. Names of these files are target |
23 | | - locale names, usually just 2-letter language codes. `Translating |
24 | | - Messages`_ section of this document gives useful hints for |
25 | | - message translators. |
26 | | - |
27 | | -4. Translated Message Files are compiled into binary form (MO files) |
28 | | - and stored in ``locale`` directory (but not kept in the `Roundup |
29 | | - CVS`_ repository, as they may be easily made from PO files). |
30 | | - See `Compiling Message Catalogs`_ section. |
31 | | - |
32 | | -5. Roundup installer creates runtime locale structure on the file |
33 | | - system, putting MO files in their appropriate places. |
34 | | - |
35 | | -6. Runtime internationalization (I18N) services use these MO files |
36 | | - to translate program messages into language selected by current |
37 | | - Roundup user. Roundup command line interface uses locale name |
38 | | - set in OS environment variable ``LANGUAGE``, ``LC_ALL``, |
39 | | - ``LC_MESSAGES``, or ``LANG`` (in that order). Roundup Web User |
40 | | - Interface uses language selected by currentluy authenticated user. |
41 | | - |
42 | | -Additional details may be found in `GNU gettext`_ and Python `gettext |
43 | | -module`_ documentation. |
44 | | - |
45 | | -`Roundup source distribution`_ includes POT and PO files for message |
46 | | -translators, and also pre-built MO files to facilitate installations |
47 | | -from source. `Roundup binary distribution`_ includes MO files only. |
48 | | - |
49 | | -.. _GNU gettext: |
50 | | - |
51 | | -GNU gettext package |
52 | | -------------------- |
53 | | - |
54 | | -This document is full of references to `GNU`_ `gettext package`_. |
55 | | -GNU gettext is a "must have" for nearly all steps of internationalizing |
56 | | -any program, and it's manual is definetely a recommended reading |
57 | | -for people involved in I18N. |
58 | | - |
59 | | -There are GNU gettext ports to all major OS platforms. |
60 | | -Windows binaries are available from ``GNU mirror sites``. |
61 | | - |
62 | | -Roundup does not use GNU gettext at runtime, but it's tools |
63 | | -are used for `extracting translatable messages`_, `compiling |
64 | | -message catalogs`_ and, optionally, for `translating messages`_. |
65 | | - |
66 | | -Note that ``gettext`` package in some OS distributions (e.g. |
67 | | -`FreeBSD`_) means just runtime libraries. Development tools |
68 | | -are usually distributed in separate package named ``gettext-devel``. |
69 | | - |
70 | | -Marking Strings for Translation |
71 | | -------------------------------- |
72 | | - |
73 | | -Strings that need translation must be marked in the source code. |
74 | | -Following sections of this chapter explain how this is done in |
75 | | -different cases. |
76 | | - |
77 | | -Current status of the string marks in Roundup core files is shown |
78 | | -in `I18 Status`_ section at the end of this document. |
79 | | - |
80 | | -If translatable string is used as a format string, it is recommended |
81 | | -to always use named format specifiers:: |
82 | | - |
83 | | - _('Index of %(classname)s') % locals() |
84 | | - |
85 | | -This helps translators to better understand the context of the |
86 | | -message and, in Python, remove format specifier altogether (which |
87 | | -is sometimes useful, especially in singular cases of `Plural Forms`_). |
88 | | -When there is more than one format specifier in the translatable |
89 | | -format string, named format specifiers *must* be used almost always, |
90 | | -because translation may require different order of items. |
91 | | - |
92 | | -It is better to *not* mark for translation strings that are not |
93 | | -locale-dependent, as this makes it more difficult to keep track |
94 | | -of translation completeness. For example: following string in |
95 | | -``index()`` method of the request handler in ``roundup_server`` |
96 | | -script:: |
97 | | - |
98 | | - </ol></body></html> |
99 | | - |
100 | | -has no human readable parts at all, and needs no translations. |
101 | | -These strings are left untranslated in PO files, and are reported |
102 | | -as such by PO status checkers (e.g. ``msgfmt --statistics``). |
103 | | - |
104 | | -Command Line Interfaces |
105 | | -~~~~~~~~~~~~~~~~~~~~~~~ |
106 | | - |
107 | | -Scripts and routines run from the command line use "static" language |
108 | | -defined by environment variables recognized by ``gettext`` module |
109 | | -from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and |
110 | | -``LANG``). Primarilly, these are ``roundup-admin`` script and |
111 | | -``admin.py`` module, but also help texts and startup error messages |
112 | | -in other scripts and their supporting modules. |
113 | | - |
114 | | -For these interfaces, Python ``gettext`` engine must be initialized |
115 | | -to use Roundup message catalogs. This is normally done by including |
116 | | -the following line in the module imports:: |
117 | | - |
118 | | - from i18n import _, ngettext |
119 | | - |
120 | | -Simple translations are automatically marked by calls to builtin |
121 | | -message translation function ``_()``:: |
122 | | - |
123 | | - print _("This message is translated") |
124 | | - |
125 | | -Translations for messages whose grammatical depends on a number |
126 | | -must be done by ``ngettext()`` function:: |
127 | | - |
128 | | - print ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked) |
129 | | - |
130 | | -User Interfaces |
131 | | -~~~~~~~~~~~~~~~ |
132 | | - |
133 | | -*(not yet)* |
134 | | - |
135 | | -This includes Mail Gateway and Web User Interfaces, where translation |
136 | | -depends on the language of current Roundup User. These translations |
137 | | -will be done by the tracker configuration object. Translatable strings |
138 | | -will be automatically marked by calls to the ``_()`` and ``ngettext()`` |
139 | | -methods of that object:: |
140 | | - |
141 | | - self.config._("This message is translated") |
142 | | - self.config.ngettext("Nuked %i file", "Nuked %i files", |
143 | | - number_of_files_nuked) |
144 | | - |
145 | | -Deferred Translations |
146 | | -~~~~~~~~~~~~~~~~~~~~~ |
147 | | - |
148 | | -Sometimes translatable strings appear in the source code in untranslated |
149 | | -form [#note_admin.py]_ and must be translated elsewhere. |
150 | | -Example:: |
151 | | - |
152 | | - for meal in ("spam", "egg", "beacon"): |
153 | | - print _(meal) |
154 | | - |
155 | | -In such cases, strings must be marked for translation without actual |
156 | | -call to the translating function. To mark these strings, we use Python |
157 | | -feature of automatical concatenation of adjacent strings and different |
158 | | -types of string quotes:: |
159 | | - |
160 | | - strings_to_translate = ( |
161 | | - ''"This string will be translated", |
162 | | - ""'me too', |
163 | | - ''r"\raw string", |
164 | | - ''""" |
165 | | - multiline string""" |
166 | | - ) |
167 | | - |
168 | | -.. [#note_admin.py] In current Roundup sources, this feature is |
169 | | - extensively used in the ``admin`` module using method docstrings |
170 | | - as help messages. |
171 | | - |
172 | | -Extracting Translatable Messages |
173 | | --------------------------------- |
174 | | - |
175 | | -The most common tool for message extraction is ``xgettext`` utility |
176 | | -from `GNU gettext package`_. Unfortunately, this utility has no means |
177 | | -of `Deferred Translations`_ in Python sources. |
178 | | -There is ``xpot`` tool from Francois Pinard free `PO utilities`_ |
179 | | -that allows to mark strings for `deferred translations`_, but |
180 | | -it does not handle `plural forms`_. |
181 | | -Roundup overcomes these limitations by using both of these utilities. |
182 | | -This means that you need both `GNU gettext`_ tools and `PO utilities`_ |
183 | | -to build the Message Template File yourself. |
184 | | - |
185 | | -Latest Message Template File is kept in `Roundup CVS`_ and distributed |
186 | | -with `Roundup Source`_. |
187 | | -If you wish to rebuild the template yourself, make sure that you have |
188 | | -both ``xpot`` and ``xgettext`` installed and just run ``gmake`` (or |
189 | | -``make``, if you are on a `GNU`_ system like `linux`_ or `cygwin`_) |
190 | | -in the ``locale`` directory. |
191 | | - |
192 | | -Translating Messages |
193 | | --------------------- |
194 | | - |
195 | | -FIXME! |
196 | | - |
197 | | -Compiling Message Catalogs |
198 | | --------------------------- |
199 | | - |
200 | | -FIXME! |
201 | | - |
202 | 1 | I18 Status |
203 | 2 | ---------- |
204 | 3 |
|
@@ -283,25 +82,3 @@ test/test_multipart.py |
283 | 82 | test/test_schema.py |
284 | 83 | test/test_templating.py |
285 | 84 | test/unittest.py |
286 | | - |
287 | | -.. External hyperlink targets |
288 | | - |
289 | | -.. _cygwin: http://www.cygwin.com/ |
290 | | -.. _emacs: http://www.gnu.org/software/emacs/ |
291 | | -.. _gettext package: http://www.gnu.org/software/gettext/ |
292 | | -.. _gettext module: http://docs.python.org/lib/module-gettext.html |
293 | | -.. _GNU: http://www.gnu.org/ |
294 | | -.. _GNU mirror sites: http://www.gnu.org/prep/ftp.html |
295 | | -.. _FreeBSD: http://www.freebsd.org/ |
296 | | -.. _linux: http://www.linux.org/ |
297 | | -.. _Plural Forms: |
298 | | - http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html |
299 | | -.. _po filetype plugin: |
300 | | - http://vim.sourceforge.net/scripts/script.php?script_id=695 |
301 | | -.. _PO utilities: http://po-utils.progiciels-bpi.ca/ |
302 | | -.. _poEdit: http://poedit.sourceforge.net/ |
303 | | -.. _Roundup CVS: http://sourceforge.net/cvs/?group_id=31577 |
304 | | -.. _Roundup Source: |
305 | | -.. _Roundup source distribution: |
306 | | -.. _Roundup binary distribution: |
307 | | - http://sourceforge.net/project/showfiles.php?group_id=31577 |
0 commit comments