Mercurial > p > roundup > code
annotate doc/developers.txt @ 3696:790363e96852
Sorting/grouping by multiple properties.
- Implement sorting/grouping by multiple properties for the web
interface. I'm now using @sort0/@sortdir0,@sort1/@sortdir1,... and
@group0/@groupdir0,... when generating URLs from a search template.
These are converted to a list internally. When saving URLs (e.g. when
storing queries) I'm using @sort=prop1,prop2,... and @group=... with
optional '-' prepended to individual props.
This means saved URLs are backward compatible with existing trackers
(and yes, this was a design goal).
I need the clumsy version with @sort0,@sort1 etc, because I'm
currently using several selectors and checkboxes (as the classic
template does, too). I don't think there is a way around that in HTML?
- Updated (hopefully all) documentation to reflect the new URL format
and the consequences in the web-interface.
- I've set the number of sort/group properties in the classic template
to two -- this can easily be reverted by changing n_sort to 1.
Richard, would you look over these changes? I've set a tag before and
(will set) after commit, so that it would be easy to merge out.
Don't be too scared about the size of the change, most is documentation,
the guts are in cgi/templating.py and small changes in the classic
template.
| author | Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net> |
|---|---|
| date | Wed, 30 Aug 2006 20:28:26 +0000 |
| parents | ff234c87b28a |
| children | be9122d753c5 |
| rev | line source |
|---|---|
|
688
b38f4f95bffd
More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents:
686
diff
changeset
|
1 ================== |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
2 Developing Roundup |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
3 ================== |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
4 |
|
3643
ff234c87b28a
link to feature tracker
Richard Jones <richard@users.sourceforge.net>
parents:
3626
diff
changeset
|
5 :Version: $Revision: 1.16 $ |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
6 |
| 2409 | 7 .. note:: |
| 8 The intended audience of this document is the developers of the core | |
| 9 Roundup code. If you just wish to alter some behaviour of your Roundup | |
| 10 installation, see `customising roundup`_. | |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
11 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
12 .. contents:: |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
13 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
14 Getting Started |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
15 --------------- |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
16 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
17 Anyone wishing to help in the development of Roundup must read `Roundup's |
|
688
b38f4f95bffd
More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents:
686
diff
changeset
|
18 Design Document`_ and the `implementation notes`_. |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
19 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
20 All development is coordinated through two resources: |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
21 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
22 - roundup-dev mailing list at |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
23 http://lists.sourceforge.net/mailman/listinfo/roundup-devel |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
24 - Sourceforge's issue trackers at |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
25 https://sourceforge.net/tracker/?group_id=31577 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
26 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
27 Small Changes |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
28 ------------- |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
29 |
|
3643
ff234c87b28a
link to feature tracker
Richard Jones <richard@users.sourceforge.net>
parents:
3626
diff
changeset
|
30 Most small changes can be submitted through the `feature tracker`_, with |
|
ff234c87b28a
link to feature tracker
Richard Jones <richard@users.sourceforge.net>
parents:
3626
diff
changeset
|
31 patches attached that give context diffs of the affected source. |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
32 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
33 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
34 CVS Access |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
35 ---------- |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
36 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
37 To get CVS access, contact richard@users.sourceforge.net. |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
38 |
|
1244
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
39 CVS stuff: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
40 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
41 1. to tag a release (eg. the pre-release of 0.5.0):: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
42 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
43 cvs tag release-0-5-0-pr1 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
44 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
45 1. to make a branch (eg. branching for code freeze/release):: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
46 |
|
2273
c77483d2cda4
merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents:
1247
diff
changeset
|
47 cvs co -d maint-0-5 -r release-0-5-0-pr1 roundup |
|
1244
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
48 cd maint-0-5 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
49 cvs tag -b maint-0-5 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
50 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
51 2. to check out a branch (eg. the maintenance branch for 0.5.x):: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
52 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
53 cvs co -d maint-0-5 -r maint-0-5 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
54 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
55 3. to merge changes from the maintenance branch to the trunk, in the |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
56 directory containing the HEAD checkout:: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
57 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
58 cvs up -j maint-0-5 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
59 |
| 1247 | 60 though this is highly discouraged, as it generally creates a whole swag |
| 61 of conflicts :( | |
| 62 | |
|
1244
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
63 Standard tag names: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
64 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
65 *release-maj-min-patch[-sub]* |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
66 Release of the major.minor.patch release, possibly a beta or pre-release, |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
67 in which case *sub* will be one of "b*N*" or "pr*N*". |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
68 *maint-maj-min* |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
69 Maintenance branch for the major.minor release. Patch releases are tagged in |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
70 this branch. |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
71 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
72 Typically, release happen like this: |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
73 |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
74 1. work progresses in the HEAD branch until milestones are met, |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
75 2. a series of beta releases are tagged in the HEAD until the code is |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
76 stable enough to freeze, |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
77 3. the pre-release is tagged in the HEAD, with the resultant code branched |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
78 to the maintenance branch for that release, |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
79 4. bugs in the release are patched in the maintenance branch, and the final |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
80 and patch releases are tagged there, and |
|
8dd4f736370b
merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents:
1089
diff
changeset
|
81 5. further major work happens in the HEAD. |
| 935 | 82 |
| 83 Project Rules | |
| 84 ------------- | |
| 85 | |
| 86 Mostly the project follows Guido's Style (though naming tends to be a little | |
| 87 relaxed sometimes). In short: | |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
88 |
| 935 | 89 - 80 column width code |
| 90 - 4-space indentations | |
| 2301 | 91 - All modules must have a CVS Id line near the top |
| 935 | 92 |
| 93 Other project rules: | |
| 94 | |
| 95 - New functionality must be documented, even briefly (so at least we know | |
|
1089
43ab730ee194
instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents:
935
diff
changeset
|
96 where there's missing documentation) and changes to tracker configuration |
| 935 | 97 must be logged in the upgrading document. |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
98 - subscribe to roundup-checkins to receive checkin notifications from the |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
99 other developers with CVS access |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
100 - discuss any changes with the other developers on roundup-dev. If nothing |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
101 else, this makes sure there's no rude shocks |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
102 - write unit tests for changes you make (where possible), and ensure that |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
103 all unit tests run before committing changes |
| 935 | 104 - run pychecker over changed code |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
105 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
106 The administrators of the project reserve the right to boot developers who |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
107 consistently check in code which is either broken or takes the codebase in |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
108 directions that have not been agreed to. |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
109 |
|
2605
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
110 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
111 Debugging Aids |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
112 -------------- |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
113 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
114 Try turning on logging of DEBUG level messages. This may be done a number |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
115 of ways, depending on what it is you're testing: |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
116 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
117 1. If you're testing the database unit tests, then set the environment |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
118 variable ``LOGGING_LEVEL=DEBUG``. This may be done like so: |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
119 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
120 LOGGING_LEVEL=DEBUG python run_tests.py |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
121 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
122 This variable replaces the older HYPERDBDEBUG environment var. |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
123 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
124 2. If you're testing a particular tracker, then set the logging level in |
|
2921
ad4fb8a14a97
more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents:
2832
diff
changeset
|
125 your tracker's ``config.ini``. |
|
2605
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
126 |
|
6e9bd67fefa9
complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
127 |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
128 Internationalization Notes |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
129 -------------------------- |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
130 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
131 How stuff works: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
132 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
133 1. Strings that may require translation (messages in human language) |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
134 are marked in the source code. This step is discussed in |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
135 `Marking Strings for Translation`_ section. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
136 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
137 2. These strings are all extracted into Message Template File |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
138 ``locale/roundup.pot`` (_`POT` file). See `Extracting Translatable |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
139 Messages`_ below. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
140 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
141 3. Language teams use POT file to make Message Files for national |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
142 languages (_`PO` files). All PO files for Roundup are kept in |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
143 the ``locale`` directory. Names of these files are target |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
144 locale names, usually just 2-letter language codes. `Translating |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
145 Messages`_ section of this chapter gives useful hints for |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
146 message translators. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
147 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
148 4. Translated Message Files are compiled into binary form (_`MO` files) |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
149 and stored in ``locale`` directory (but not kept in the `Roundup |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
150 CVS`_ repository, as they may be easily made from PO files). |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
151 See `Compiling Message Catalogs`_ section. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
152 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
153 5. Roundup installer creates runtime locale structure on the file |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
154 system, putting MO files in their appropriate places. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
155 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
156 6. Runtime internationalization (_`I18N`) services use these MO files |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
157 to translate program messages into language selected by current |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
158 Roundup user. Roundup command line interface uses locale name |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
159 set in OS environment variable ``LANGUAGE``, ``LC_ALL``, |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
160 ``LC_MESSAGES``, or ``LANG`` (in that order). Roundup Web User |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
161 Interface uses language selected by currently authenticated user. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
162 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
163 Additional details may be found in `GNU gettext`_ and Python `gettext |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
164 module`_ documentation. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
165 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
166 `Roundup source distribution`_ includes POT and PO files for message |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
167 translators, and also pre-built MO files to facilitate installations |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
168 from source. Roundup binary distribution includes MO files only. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
169 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
170 .. _GNU gettext: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
171 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
172 GNU gettext package |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
173 ^^^^^^^^^^^^^^^^^^^ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
174 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
175 This chapter is full of references to GNU `gettext package`_. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
176 GNU gettext is a "must have" for nearly all steps of internationalizing |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
177 any program, and it's manual is definetely a recommended reading |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
178 for people involved in `I18N`_. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
179 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
180 There are GNU gettext ports to all major OS platforms. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
181 Windows binaries are available from `GNU mirror sites`_. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
182 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
183 Roundup does not use GNU gettext at runtime, but it's tools |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
184 are used for `extracting translatable messages`_, `compiling |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
185 message catalogs`_ and, optionally, for `translating messages`_. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
186 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
187 Note that ``gettext`` package in some OS distributions means just |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
188 runtime tools and libraries. In such cases gettext development tools |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
189 are usually distributed in separate package named ``gettext-devel``. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
190 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
191 Marking Strings for Translation |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
193 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
194 Strings that need translation must be marked in the source code. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
195 Following subsections explain how this is done in different cases. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
196 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
197 If translatable string is used as a format string, it is recommended |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
198 to always use *named* format specifiers:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
199 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
200 _('Index of %(classname)s') % locals() |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
201 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
202 This helps translators to better understand the context of the |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
203 message and, with Python formatting, remove format specifier altogether |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
204 (which is sometimes useful, especially in singular cases of `Plural Forms`_). |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
205 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
206 When there is more than one format specifier in the translatable |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
207 format string, named format specifiers **must** be used almost always, |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
208 because translation may require different order of items. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
209 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
210 It is better to *not* mark for translation strings that are not |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
211 locale-dependent, as this makes it more difficult to keep track |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
212 of translation completeness. For example, string ``</ol></body></html>`` |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
213 (in ``index()`` method of the request handler in ``roundup_server`` |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
214 script) has no human readable parts at all, and needs no translations. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
215 Such strings are left untranslated in PO files, and are reported |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
216 as such by PO status checkers (e.g. ``msgfmt --statistics``). |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
217 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
218 Command Line Interfaces |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
219 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
220 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
221 Scripts and routines run from the command line use "static" language |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
222 defined by environment variables recognized by ``gettext`` module |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
223 from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
224 ``LANG``). Primarilly, these are ``roundup-admin`` script and |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
225 ``admin.py`` module, but also help texts and startup error messages |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
226 in other scripts and their supporting modules. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
227 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
228 For these interfaces, Python ``gettext`` engine must be initialized |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
229 to use Roundup message catalogs. This is normally done by including |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
230 the following line in the module imports:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
231 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
232 from i18n import _, ngettext |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
233 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
234 Simple translations are automatically marked by calls to builtin |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
235 message translation function ``_()``:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
236 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
237 print _("This message is translated") |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
238 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
239 Translations for messages whose grammatical depends on a number |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
240 must be done by ``ngettext()`` function:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
241 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
242 print ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked) |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
243 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
244 Deferred Translations |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
245 ~~~~~~~~~~~~~~~~~~~~~ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
246 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
247 Sometimes translatable strings appear in the source code in untranslated |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
248 form [#note_admin.py]_ and must be translated elsewhere. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
249 Example:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
250 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
251 for meal in ("spam", "egg", "beacon"): |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
252 print _(meal) |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
253 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
254 In such cases, strings must be marked for translation without actual |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
255 call to the translating function. To mark these strings, we use Python |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
256 feature of automatic concatenation of adjacent strings and different |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
257 types of string quotes:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
258 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
259 strings_to_translate = ( |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
260 ''"This string will be translated", |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
261 ""'me too', |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
262 ''r"\raw string", |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
263 ''""" |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
264 multiline string""" |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
265 ) |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
266 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
267 .. [#note_admin.py] In current Roundup sources, this feature is |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
268 extensively used in the ``admin`` module using method docstrings |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
269 as help messages. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
270 |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
271 Web User Interface |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
272 ~~~~~~~~~~~~~~~~~~ |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
273 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
274 For Web User Interface, translation services are provided by Client |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
275 object. Action classes have methods ``_()`` and ``gettext()``, |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
276 delegating translation to the Client instance. In HTML templates, |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
277 translator object is available as context variable ``i18n``. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
278 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
279 HTML templates have special markup for translatable strings. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
280 The syntax for this markup is defined on `ZPTInternationalizationSupport`_ |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
281 page. Roundup translation service currently ignores values for |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
282 ``i18n:domain``, ``i18n:source`` and ``i18n:target``. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
283 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
284 Template markup examples: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
285 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
286 * simplest case:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
287 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
288 <div i18n:translate=""> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
289 Say |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
290 no |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
291 more! |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
292 </div> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
293 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
294 this will result in msgid ``"Say no more!"``, with all leading and |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
295 trailing whitespace stripped, and inner blanks replaced with single |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
296 space character. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
297 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
298 * using variable slots:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
299 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
300 <div i18n:translate=""> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
301 And now...<br/> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
302 No.<span tal:replace="number" i18n:name="slideNo" /><br/> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
303 THE LARCH |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
304 </div> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
305 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
306 Msgid will be: ``"And now...<br /> No.${slideNo}<br /> THE LARCH"``. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
307 Template rendering will use context variable ``number`` (you may use |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
308 any expression) to put instead of ``${slideNo}`` in translation. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
309 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
310 * attribute translation:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
311 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
312 <button name="btn_wink" value=" Wink " i18n:attributes="value" /> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
313 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
314 will translate the caption (and return value) for the "wink" button. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
315 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
316 * explicit msgids. Sometimes it may be useful to specify msgid |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
317 for the element translation explicitely, like this:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
318 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
319 <span i18n:translate="know what i mean?">this text is ignored</span> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
320 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
321 When rendered, element contents will be replaced by translation |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
322 of the string specified in ``i18n:translate`` attribute. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
323 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
324 * ``i18n`` in `TALES`_. You may translate strings in `TALES`_ python |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
325 expressions:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
326 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
327 <span tal:replace="python: i18n.gettext('Oh, wicked.')" /> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
328 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
329 * plural forms. There is no markup for plural forms in `TAL`_ i18n. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
330 You must use python expression for that:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
331 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
332 <span tal:replace="python: i18n.ngettext( |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
333 'Oh but it\'s only %i shilling.', |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
334 'Oh but it\'s only %i shillings.', |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
335 fine) % fine" |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
336 /> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
337 |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
338 Extracting Translatable Messages |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
340 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
341 The most common tool for message extraction is ``xgettext`` utility |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
342 from `GNU gettext package`_. Unfortunately, this utility has no means |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
343 of `Deferred Translations`_ in Python sources. There is ``xpot`` tool |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
344 from Francois Pinard free `PO utilities`_ that allows to mark strings |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
345 for deferred translations, but it does not handle `plural forms`_. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
346 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
347 Roundup overcomes these limitations by using both of these utilities. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
348 This means that you need both `GNU gettext`_ tools and `PO utilities`_ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
349 to build the Message Template File yourself. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
350 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
351 Latest Message Template File is kept in `Roundup CVS`_ and distributed |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
352 with `Roundup Source`_. If you wish to rebuild the template yourself, |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
353 make sure that you have both ``xpot`` and ``xgettext`` installed and |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
354 just run ``gmake`` (or ``make``, if you are on a `GNU`_ system like |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
355 `linux`_ or `cygwin`_) in the ``locale`` directory. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
356 |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
357 For on-site i18n, Roundup provides command-line utility:: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
358 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
359 roundup-gettext <tracker_home> |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
360 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
361 extracting translatable messages from tracker's html templates. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
362 This utility creates message template file ``messages.pot`` in |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
363 ``locale`` subdirectory of the tracker home directory. Translated |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
364 messages may be put in *locale*.po files (where *locale* is selected |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
365 locale name) in the same directory, e.g.: ``locale/ru.po``. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
366 These message catalogs are searched prior to system-wide translations |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
367 kept in the ``share`` directory. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
368 |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
369 Translating Messages |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
370 ^^^^^^^^^^^^^^^^^^^^ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
371 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
372 Gettext Message File (`PO`_ file) is a plain text file, that can be created |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
373 by simple copying ``roundup.pot`` to new .po file, like this:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
374 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
375 $ cp roundup.pot ru.po |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
376 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
377 The name of PO file is target locale name, usually just 2-letter language |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
378 code (``ru`` for Russian in the above example). Alternatively, PO file |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
379 may be initialized by ``msginit`` utility from `GNU gettext`_ tools:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
380 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
381 $ msginit -i roundup.pot |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
382 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
383 ``msginit`` will check your current locale, and initialize the header |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
384 entry, setting language name, rules for `plural forms`_ and, if available, |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
385 translator's name and email address. The name for PO file is also chosen |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
386 based on current locale. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
387 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
388 Next, you will need to edit this file, filling all ``msgstr`` lines with |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
389 translations of the above ``msgid`` entries. PO file is a plain text |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
390 file that can be edited with any text editor. However, there are several |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
391 tools that may help you with this process: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
392 |
|
3626
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
393 - `poEdit`_ by Vaclav Slavik. Very nice cross-platform GUI editor. |
|
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
394 |
|
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
395 - `KBabel`_. Being part of `KDE`_, it works in X windows only. |
|
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
396 At the first glance looks pretty hairy, with all bells and whistles. |
|
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
397 Haven't had much experience with it, though. |
|
3e00e0110e64
removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2921
diff
changeset
|
398 |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
399 - ``po-mode`` for `emacs`_. One of `GNU gettext`_ tools. Very handy, |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
400 definitely recommended if you are comfortable with emacs. Cannot |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
401 handle `plural forms`_ per se, but allows to edit them in simple |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
402 text mode. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
403 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
404 - `po filetype plugin`_ for `vim`_. Does not do as much as ``po-mode``, |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
405 but helps in finding untranslated and fuzzy strings, and checking |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
406 code references. Please contact `alexander smishlajev`_ if you |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
407 prefer this, as i have patched this plugin a bit. I have also |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
408 informed the original plugin author about these changes, but got |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
409 no reply so far. |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
410 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
411 Compiling Message Catalogs |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
412 ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
413 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
414 Message catalogs (`PO`_ files) must be compiled into binary form |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
415 (`MO`_ files) before they can be used in the application. This |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
416 compilation is handled by ``msgfmt`` utility from `GNU gettext`_ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
417 tools. ``GNUmakefile`` in the ``locale`` directory automatically |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
418 compiles all existing message catalogs after updating them from |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
419 Roundup source files. If you wish to rebuild an individual `MO`_ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
420 file without making everything else, you may, for example:: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
421 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
422 $ msgfmt --statistics -o ru.mo ru.po |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
423 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
424 This way, message translators can check their `PO`_ files without |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
425 extracting strings from source. (Note: String extraction requires |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
426 additional utility that is not part of `GNU gettext`_. See `Extracting |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
427 Translatable Messages`_.) |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
428 |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
429 At run time, Roundup automatically compiles message catalogs whenever |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
430 `PO`_ file is changed. |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
431 |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
432 ----------------- |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
433 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
434 Back to `Table of Contents`_ |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
435 |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
436 .. _`Table of Contents`: index.html |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
437 .. _`Customising Roundup`: customizing.html |
|
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
438 .. _`Roundup's Design Document`: spec.html |
|
688
b38f4f95bffd
More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents:
686
diff
changeset
|
439 .. _`implementation notes`: implementation.html |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
440 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
441 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
442 .. _External hyperlink targets: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
443 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
444 .. _alexander smishlajev: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
445 .. _als: http://sourceforge.net/users/a1s/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
446 .. _cygwin: http://www.cygwin.com/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
447 .. _emacs: http://www.gnu.org/software/emacs/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
448 .. _gettext package: http://www.gnu.org/software/gettext/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
449 .. _gettext module: http://docs.python.org/lib/module-gettext.html |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
450 .. _GNU: http://www.gnu.org/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
451 .. _GNU mirror sites: http://www.gnu.org/prep/ftp.html |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
452 .. _KBabel: http://i18n.kde.org/tools/kbabel/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
453 .. _KDE: http://www.kde.org/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
454 .. _linux: http://www.linux.org/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
455 .. _Plural Forms: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
456 http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
457 .. _po filetype plugin: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
458 http://vim.sourceforge.net/scripts/script.php?script_id=695 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
459 .. _PO utilities: http://po-utils.progiciels-bpi.ca/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
460 .. _poEdit: http://poedit.sourceforge.net/ |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
461 .. _Roundup CVS: http://sourceforge.net/cvs/?group_id=31577 |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
462 .. _Roundup Source: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
463 .. _Roundup source distribution: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
464 .. _Roundup binary distribution: |
|
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
465 http://sourceforge.net/project/showfiles.php?group_id=31577 |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
466 .. _TAL: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
467 .. _Template Attribute Language: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
468 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4 |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
469 .. _TALES: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
470 .. _Template Attribute Language Expression Syntax: |
|
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
471 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3 |
|
2353
bf3f75134e03
i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2301
diff
changeset
|
472 .. _vim: http://www.vim.org/ |
|
2832
47766d279878
Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2605
diff
changeset
|
473 .. _ZPTInternationalizationSupport: http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport |
|
3643
ff234c87b28a
link to feature tracker
Richard Jones <richard@users.sourceforge.net>
parents:
3626
diff
changeset
|
474 .. _feature tracker: http://sourceforge.net/tracker/?group_id=31577&atid=402791 |
|
ff234c87b28a
link to feature tracker
Richard Jones <richard@users.sourceforge.net>
parents:
3626
diff
changeset
|
475 |
