Mercurial > p > roundup > code

annotate doc/developers.txt @ 7740:67438e439da8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: issue2551317 add support for jinja2 customization examples Added sphinx-tabs to doc build. This allows adding code-tabs one for "TAL" examples and one for "Jinja2" examples in the doc. Converted partly the "Editing multiple items in an index view" example. Sombody who knows jinja2 better than I, and can test the example will need to finish it. Documented requirement and method for building docs in developers.txt. Added requirements.pip files for pip install -r ... modules needed for processing docs. Fixed missing block in layout.txt that stopped tabs.css from being loaded.
author John Rouillard <rouilj@ieee.org>
date Sat, 17 Feb 2024 18:56:04 -0500
parents 3134415ffb8a
children a46675399a05
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2386
diff changeset
5 .. note::
Richard Jones <richard@users.sourceforge.net>
parents: 2386
diff changeset
6 The intended audience of this document is the developers of the core
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
7 Roundup code. If you just wish to alter some behavior of your Roundup
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
8 installation, see `Customising Roundup`_.
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4731
diff changeset
10 Contents
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4731
diff changeset
11
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 .. contents::
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4731
diff changeset
13 :local:
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
6343
bea4a6956c89 Moved roundup-tracker.org infrastructure docs to website/README.txt
John Rouillard <rouilj@ieee.org>
parents: 6265
diff changeset
15
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 Getting Started
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 ---------------
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
19 If you are looking for a good first issue, search for `StarterTicket
7135
d0ef168a9379 Fix bad capitalization of Roundup in url's.
John Rouillard <rouilj@ieee.org>
parents: 7101
diff changeset
20 on https://issues.roundup-tracker.org`_. These include issues where
d0ef168a9379 Fix bad capitalization of Roundup in url's.
John Rouillard <rouilj@ieee.org>
parents: 7101
diff changeset
21 Python development, documentation or web design skills are useful.
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
22
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
23 You can continue the conversation using the issue or join the
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
24 Roundup-devel list to get assistance and verify your planned changes.
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 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
27
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
28 - roundup-devel mailing list at
7135
d0ef168a9379 Fix bad capitalization of Roundup in url's.
John Rouillard <rouilj@ieee.org>
parents: 7101
diff changeset
29 https://sourceforge.net/projects/roundup/lists/roundup-devel
4254
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
30 - The issue tracker running at
7135
d0ef168a9379 Fix bad capitalization of Roundup in url's.
John Rouillard <rouilj@ieee.org>
parents: 7101
diff changeset
31 https://issues.roundup-tracker.org/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
32
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
33 In addition, the Roundup IRC channel on irc.oftc.net can be accessed
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
34 via the web interface shown on the Contact page. The channel is logged
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
35 and the web sites for the logs are shown in the channel topic. You can
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
36 ask questions and use it to coordinate work discussed using the
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
37 resources above.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
38
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
39 Anyone wishing to help in the development of the Roundup Python core
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
40 may find `Roundup's Design Document`_ and the `implementation notes`_
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
41 helpful.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
42
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
43 People working on Documentation or designing changes to the Web
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
44 interface don't need to get into the implementation internals.
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
46 Project Rules
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
47 -------------
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
48
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
49 Be polite to others. There is no place for ad hominem attacks.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
50
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
51 Mostly the project follows Guido's Python Style (though naming tends
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
52 to be a little relaxed sometimes). In short:
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
54 - 80 column width code
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
55 - 4-space indentations
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
56
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
57 Other project rules:
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
58
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
59 - new functionality must be documented, even briefly (so at
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
60 least we know where there's missing documentation) and
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
61 changes to tracker configuration must be logged in the
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
62 upgrading document.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
63 - discuss any changes with the other developers on
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
64 roundup-dev. If nothing else, this makes sure there's no
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
65 rude shocks.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
66 - write unit tests for changes you make (where possible),
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
67 and ensure that all unit tests run before committing
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
68 changes.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
69 - run flake8_ or pylint_ over changed code.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
70 - if you have direct commit access to the repository,
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
71 subscribe to roundup-checkins to receive checkin
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
72 notifications from the other developers with write access
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
73 to the source-code repository.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
74
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
75 The goal is to have no flake8 issues. Current code has
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
76 complex functions, some long lines and use of mutable
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
77 objects in function signatures. Some third party code
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
78 (e.g. ZPT) vendored into the codebase has more issues.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
79
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
80 The administrators of the project reserve the right to boot
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
81 developers who consistently check in code which is either
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
82 broken or takes the codebase in directions that have not
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
83 been agreed to.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
84
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
85 Setting up a Development Environment
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
86 ------------------------------------
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
88 Roundup doesn't require any external libraries. Installing
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
89 Python 3 and its core libraries is enough to get Roundup
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
90 running.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
91
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
92 The easiest way to work with Roundup is to clone the
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
93 repository. Roundup is developed using the `Mercurial
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
94 distributed version control system (DVCS)`_ [1]_. It is
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
95 `hosted at Sourceforge`_. See
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
96 https://www.roundup-tracker.org/code.html for details.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
97
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
98 If you are used to git, Mercurial's `command equivalence
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
99 table`_ can help. Most of the concepts from git (except for
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
100 staging) should be familiar.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
101
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
102 To clone the repository use::
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
103
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
104 hg clone http://hg.code.sf.net/p/roundup/code roundup
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
106 (Yes, that is an http url.)
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
107
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
108 This will create a read only clone (you can't ``hg push``)
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
109 of the repo. Changes you make can be attached as patches
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
110 (created using ``hg diff``) to tickets in our `issue
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
111 tracker`_.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
112
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
113 See https://www.roundup-tracker.org/code.html for URL's and
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
114 directions on getting read write access which allows pushing
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
115 to the repository.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
116
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
117 Once you have your clone, you can run ``python3 ./demo -b
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
118 sqlite`` and get a working Roundup server. This will start
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
119 the server using the ``sqlite`` backend. The code is in the
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
120 ``roundup`` subdirectory.
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
121
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
122 Submitting Changes
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
123 ------------------
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
124
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
125 Most small changes can be submitted as patches through the
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
126 `issue tracker`_ or sent to `Roundup-devel mailing list`_.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
127
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
128 Your account on sourceforge can be set up to allow direct
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
129 pushes to the repo. Once that is done, using::
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
130
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
131 hg push https://user@hg.code.sf.net/p/roundup/code
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
132
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
133 or
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
134
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
135 hg push ssh://user@hg.code.sf.net/p/roundup/code
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
136
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
137 will commit your changes.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
138
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
139
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
140 Other Resources - CI, Code Coverage
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
141 -----------------------------------
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
142
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
143 Roundup has a `copy of the mercurial repository on GitHub`_. It is
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
144 updated manually after every few commits to the Mercurial
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
145 repository. Updates trigger the CI pipeline which happens on two
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
146 services:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
147
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
148 1. `GitHub Actions`_. It runs Docker container scans using Anchore as
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
149 well as security scans for dependencies using CodeQL. Also it
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
150 runs the test suite on multiple versions of Python.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
151 2. `TravisCI`_ is also used to run CI. It runs the test suite on
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
152 multiple Python versions. It also provides alpha and development
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
153 Python releases faster than GitHub.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
154
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
155 GitHub actions upload coverage statistics to both `CodeCov`_ and
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
156 `Coveralls`_. TravisCI only uploads to CodeCov.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
157
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
158 We run our own issue tracker so we can dogfood the code. As
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
159 a result, we do not use GitHub issues. Pull requests are
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
160 grudgingly accepted. They have to be exported and applied to
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
161 the Mercurial repository. This is time consuming so patches
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
162 attached to an issue in our tracker are preferred.
2605
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
163
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
164 Debugging Aids
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
165 --------------
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
166
7322
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
167 Try turning on logging of DEBUG level messages. This may be done a number
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
168 of ways, depending on what it is you're testing:
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
169
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
170 1. If you're testing the database unit tests, then set the environment
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
171 variable ``LOGGING_LEVEL=DEBUG``. This may be done like so:
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
172
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
173 LOGGING_LEVEL=DEBUG python -m pytest test/
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
174
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
175 This variable replaces the older HYPERDBDEBUG environment var.
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
176
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
177 2. If you're testing a particular tracker, then set the logging level in
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
178 your tracker's ``config.ini``.
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
179
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
180 If you set the environment variable SENDMAILDEBUG to a filename,
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
181 roundup will write each email message that it sends to that file
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
182 instead to the internet. This environment variable is independent of
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
183 the python -O flag.
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
184
7740
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
185 Documentation Notes
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
186 -------------------
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
187
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
188 All docs are written using sphinx. Use pip or your package manager to
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
189 install sphinx. In addition you will need to install a couple of
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
190 sphinx extensions to process the files. A requirement's file can be
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
191 found in docs/requirement.pip or website/www/requirements.pip. You can
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
192 install these requirements using ``python -m pip install -r
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
193 <path_to_requirements_file>``.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
194
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
195 The extensions sphinx-sitemap generates a sitemap when building for
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
196 the website. The sphinx-tabs extension generates tabs for displaying
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
197 code examples in both TAL and Jinja2.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
198
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
199 To build the documentation distributed with a Roundup release, run
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
200 ``python setup.py build_doc`` at the root of the source tree. To build
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
201 docs for the website, see the ``updating www.roundup-tracker.org``
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
202 section of ``website/README.txt`` or TL;DR ``cd website/www; make
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
203 html``.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
204
7475
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
205 Testing Notes
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
206 -------------
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
207
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
208 Create tests for your changes. Also run the tests in reverse to try to
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
209 identify test dependencies. You can do this by creating a
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
210 ``conftest.py`` in the top of the source tree and include the
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
211 following contents::
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
212
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
213 def pytest_collection_modifyitems(items):
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
214 items.reverse()
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
215
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
216 to run all the tests in reverse. More tips at: https://testmon.org/blog/hidden-test-dependencies/.
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
217
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
218 The full test suite can take a while to run. The `pytest-testmon
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
219 <https://pypi.org/project/pytest-testmon/>`_ package can be installed
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
220 with pip. It analyzes changes to code and run tests that test that
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
221 code. This can significantly reduce the time it takes to run a basic
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
222 test suite. Use it by running::
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
223
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
224 python3 -m pytest -v --testmon test
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
225
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
226 once over the whole test suite. Then subsequent calls will analyze the
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
227 changed files/functions and run tests that cover those changes.
2605
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
228
7592
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
229 To run some tests (test_liveserver.py, test_indexer.py, ...) you need
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
230 to have some additional modules installed. These include:
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
231
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
232 * requests
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
233 * mock
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
234
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
235 If you are working with a docker container that is set up to execute
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
236 Python application and not for development, you will need to install
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
237 pytest.
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
238
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
239 Internationalization Notes
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
240 --------------------------
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 How stuff works:
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 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
245 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
246 `Marking Strings for Translation`_ section.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
247
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
248 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
249 ``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
250 Messages`_ below.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
251
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
252 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
253 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
254 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
255 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
256 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
257 message translators.
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 4. Translated Message Files are compiled into binary form (_`MO` files)
4254
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
260 and stored in ``locale`` directory (but not kept in the source code
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
261 repository, as they may be easily made from PO files).
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
262 See `Compiling Message Catalogs`_ section.
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 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
265 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
266
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
267 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
268 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
269 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
270 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
271 ``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
272 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
273
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
274 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
275 module`_ documentation.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
276
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
277 `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
278 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
279 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
280
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
281 .. _GNU gettext:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
282
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
283 GNU gettext package
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
284 ~~~~~~~~~~~~~~~~~~~
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
285
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
286 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
287 GNU gettext is a "must have" for nearly all steps of internationalizing
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
288 any program, and it's manual is definitely a recommended reading
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
289 for people involved in `I18N`_.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
290
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
291 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
292 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
293
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
294 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
295 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
296 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
297
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
298 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
299 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
300 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
301
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
302 Marking Strings for Translation
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
303 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
304
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
305 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
306 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
307
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
308 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
309 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
310
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
311 _('Index of %(classname)s') % locals()
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
312
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
313 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
314 message and, with Python formatting, remove format specifier altogether
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
315 (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
316
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
317 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
318 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
319 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
320
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
321 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
322 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
323 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
324 (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
325 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
326 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
327 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
328
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
329 Command Line Interfaces
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
330 ~~~~~~~~~~~~~~~~~~~~~~~
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
331
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
332 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
333 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
334 from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
6184
c757a6a14c8d Fix spelling of primarily.
John Rouillard <rouilj@ieee.org>
parents: 5941
diff changeset
335 ``LANG``). Primarily, these are ``roundup-admin`` script and
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
336 ``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
337 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
338
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
339 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
340 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
341 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
342
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
343 from i18n import _, ngettext
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
344
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
345 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
346 message translation function ``_()``::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
347
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
348 print(_("This message is translated"))
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
349
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
350 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
351 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
352
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
353 print(ngettext("Nuked %i file", "Nuked %i files", number_of_files_nuked))
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
354
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
355 Deferred Translations
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
356 ~~~~~~~~~~~~~~~~~~~~~
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
357
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
358 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
359 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
360 Example::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
361
7054
d3346c3d92f2 replace beacon with bacon in list of meal items.
John Rouillard <rouilj@ieee.org>
parents: 6836
diff changeset
362 for meal in ("spam", "egg", "bacon"):
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
363 print(_(meal))
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
364
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
365 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
366 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
367 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
368 types of string quotes::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
369
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
370 strings_to_translate = (
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
371 ''"This string will be translated",
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
372 ""'me too',
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
373 ''r"\raw string",
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 multiline string"""
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
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
378 .. [#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
379 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
380 as help messages.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
381
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
382 Web User Interface
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
383 ~~~~~~~~~~~~~~~~~~
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
384
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
385 For Web User Interface, translation services are provided by Client
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
386 object. Action classes have methods ``_()`` and ``gettext()``,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
387 delegating translation to the Client instance. In HTML templates,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
388 translator object is available as context variable ``i18n``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
389
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
390 HTML templates have special markup for translatable strings.
6456
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
391 The syntax for this markup is discussed at `ZPTInternationalization`_.
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
392 (Originally documented at
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
393 http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
394 which is now gone.)
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
395 Roundup translation service currently ignores values for
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
396 ``i18n:domain``, ``i18n:source`` and ``i18n:target``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
397
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
398 Template markup examples:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
399
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
400 * simplest case::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
401
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
402 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
403 Say
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
404 no
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
405 more!
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
406 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
407
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
408 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
409 trailing whitespace stripped, and inner blanks replaced with single
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
410 space character.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
411
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
412 * using variable slots::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
413
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
414 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
415 And now...<br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
416 No.<span tal:replace="number" i18n:name="slideNo" /><br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
417 THE LARCH
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
418 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
419
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
420 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
421 Template rendering will use context variable ``number`` (you may use
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
422 any expression) to put instead of ``${slideNo}`` in translation.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
423
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
424 * attribute translation::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
425
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
426 <button name="btn_wink" value=" Wink " i18n:attributes="value" />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
427
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
428 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
429
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
430 * explicit msgids. Sometimes it may be useful to specify msgid
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
431 for the element translation explicitly, like this::
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
432
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
433 <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
434
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
435 When rendered, element contents will be replaced by translation
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
436 of the string specified in ``i18n:translate`` attribute.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
437
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
438 * ``i18n`` in `TALES`_. You may translate strings in `TALES`_ python
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
439 expressions::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
440
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
441 <span tal:replace="python: i18n.gettext('Oh, wicked.')" />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
442
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
443 * 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
444 You must use python expression for that::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
445
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
446 <span tal:replace="python: i18n.ngettext(
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
447 'Oh but it\'s only %i shilling.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
448 'Oh but it\'s only %i shillings.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
449 fine) % fine"
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
450 />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
451
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
452 Detectors and extensions
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
453 ^^^^^^^^^^^^^^^^^^^^^^^^
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
454
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
455 The correct ``i18n`` objects gets automatically injected in the hyperdb.
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
456 In a detector you can access the i18n object and do translation like
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
457 this::
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
458
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
459 def statusfail(db, cl, nodeid, newvalues):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
460 _ = db.i18n.gettext
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
461 raise ValueError(_("this does not work"))
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
462
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
463 def init(db):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
464 # fire before changes are made
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
465 db.status.audit('create', statusfail)
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
466
7337
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
467 .. index::
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
468 i18n; adding translations for your tracker
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
469 see: internatonalization; i18n
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
470 see: localization; i18n
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
471
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
472 Extracting Translatable Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
473 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
474
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
475 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
476 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
477 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
478 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
479 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
480
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
481 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
482 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
483 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
484
4254
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
485 Latest Message Template File is kept in the source code repository
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
486 and distributed with `Roundup Source`_.
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
487 If you wish to rebuild the template yourself,
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
488 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
489 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
490 `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
491
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
492 For on-site i18n, Roundup provides command-line utility::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
493
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
494 roundup-gettext <tracker_home>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
495
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
496 extracting translatable messages from tracker's html templates.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
497 This utility creates message template file ``messages.pot`` in
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
498 ``locale`` subdirectory of the tracker home directory. Translated
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
499 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
500 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
501 These message catalogs are searched prior to system-wide translations
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
502 kept in the ``share`` directory.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
503
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
504 Translating Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
505 ^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
506
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
507 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
508 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
509
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
510 $ cp roundup.pot ru.po
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
511
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
512 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
513 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
514 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
515
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
516 $ msginit -i roundup.pot
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
517
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
518 ``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
519 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
520 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
521 based on current locale.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
522
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
523 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
524 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
525 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
526 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
527
3626
3e00e0110e64 removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2921
diff changeset
528 - `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
529
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
530 - `Lokalize`_. A replacement for KBabel. Being part of `KDE`_, it
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
531 works in X windows only. Haven't had much experience with it, though.
3626
3e00e0110e64 removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2921
diff changeset
532
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
533 - ``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
534 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
535 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
536 text mode.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
537
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
538 - `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
539 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
540 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
541 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
542 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
543 no reply so far.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
544
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
545 Compiling Message Catalogs
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
546 ^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
547
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
548 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
549 (`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
550 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
551 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
552 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
553 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
554 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
555
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
556 $ 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
557
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
558 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
559 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
560 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
561 Translatable Messages`_.)
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
563 At run time, Roundup automatically compiles message catalogs whenever
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
564 `PO`_ file is changed.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
565
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
566 .. [1] Roundup is written in Python and we believe in using tools in
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
567 the Python ecosystem whenever possible.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
568
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
569
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
570
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 .. _`Customising Roundup`: customizing.html
4949
c3a90535f7a7 Backed out changeset 4a3a35192ad1
John Rouillard <rouilj@ieee.org>
parents: 4948
diff changeset
572 .. _`Roundup's Design Document`: spec.html
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
573 .. _`implementation notes`: implementation.html
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
574
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
575
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
576 .. _External hyperlink targets:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
577
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
578 .. _alexander smishlajev:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
579 .. _als: https://sourceforge.net/u/a1s/profile/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
580 .. _CodeCov: https://app.codecov.io/gh/roundup-tracker/roundup
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
581 .. _copy of the mercurial repository on GitHub:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
582 https://github.com/roundup-tracker/roundup
7442
623502678b97 2.3.0b1 release changes
John Rouillard <rouilj@ieee.org>
parents: 7337
diff changeset
583 .. _command equivalence table: https://wiki.mercurial-scm.org/GitConcepts#Command_equivalence_table
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
584 .. _Coveralls: https://coveralls.io/github/roundup-tracker/roundup
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
585 .. _cygwin: https://www.cygwin.com/
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
586 .. _emacs: https://www.gnu.org/software/emacs/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
587 .. _flake8: https://flake8.pycqa.org/en/latest/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
588 .. _gettext package: https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
589 .. _gettext module: https://docs.python.org/2/library/gettext.html
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
590 .. _GitHub Actions: https://github.com/roundup-tracker/roundup/actions
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
591 .. _GNU: https://www.gnu.org/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
592 .. _GNU mirror sites: https://www.gnu.org/prep/ftp.html
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
593 .. _hosted at sourceforge:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
594 https://sourceforge.net/p/roundup/code/ci/default/tree/
5610
0df5f9eeefd4 Changed references to http://issues.roundup-tracker.org to https now
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
595 .. _issue tracker: https://issues.roundup-tracker.org/
6836
a8c757a33ab1 fix link to KDE Lokalize
John Rouillard <rouilj@ieee.org>
parents: 6658
diff changeset
596 .. _Lokalize: https://apps.kde.org/lokalize/
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
597 .. _KDE: https://kde.org/
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
598 .. _linux: https://www.linux.org/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
599 .. _Mercurial distributed version control system (DVCS):
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
600 https://www.mercurial-scm.org/
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
601 .. _Plural Forms:
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
602 https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
603 .. _po filetype plugin:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
604 https://vim.sourceforge.io/scripts/script.php?script_id=695
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
605 .. _PO utilities: https://github.com/pinard/po-utils
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
606 .. _poEdit: https://poedit.net/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
607 .. _pylint: https://pylint.pycqa.org/en/latest/
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
608 .. _Roundup Source:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
609 .. _Roundup source distribution:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
610 .. _Roundup binary distribution:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
611 https://sourceforge.net/projects/roundup/files/
4730
a3ea93e39e01 doc: Remove context diff requirement for sending patches
anatoly techtonik <techtonik@gmail.com>
parents: 4665
diff changeset
612 .. _roundup-devel mailing list:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
613 https://sourceforge.net/projects/roundup/lists/roundup-devel
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
614 .. _StarterTicket on https://issues.roundup-tracker.org:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
615 https://issues.roundup-tracker.org/issue?@columns=title,id,activity,status&@sort=activity&@filter=status,keywords&status=-1,1,2&keywords=15&@dispname=Starter%20tickets
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
616 .. _TAL:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
617 .. _Template Attribute Language:
5365
979390afb001 Fix some dev.zope.org links for tales and metal.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
618 https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
619 .. _TALES:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
620 .. _Template Attribute Language Expression Syntax:
5365
979390afb001 Fix some dev.zope.org links for tales and metal.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
621 https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
622 .. _TravisCI: https://app.travis-ci.com/github/roundup-tracker/roundup
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
623 .. _vim: https://www.vim.org/
7291
ff7564af07b1 Fix link to i18n with zope/grok (how-to-internationalize-your-application)
John Rouillard <rouilj@ieee.org>
parents: 7229
diff changeset
624 .. _ZPTInternationalization: http://grok.zope.org/doc/community/view_generation/i18n_of_your_app.html
Roundup Issue Tracker: http://roundup-tracker.org/