Mercurial > p > roundup > code

annotate doc/developers.txt @ 7399:deb8e7e6d66d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Skip redis tests if unable to communicate with the server. If the redis module is in the test environment, the redis tests will not be skipped. If connecting to redis during testing fails with a ConnectionError because there is no redis server at localhost, or if it fails with an AuthenticationError, you would fail a slew of tests. This causes the tests to report as skipped if either of the two errors occurs. It is very inefficient as it fails in setup() for the tests, but at least it does report skipping the tests. Also documented how to pass the redis password to the tests in the test part of the install docs. Future note: running tests needs proper docs in development.txt (including database setup) and a link left to that doc in installation.txt.
author John Rouillard <rouilj@ieee.org>
date Wed, 24 May 2023 12:52:53 -0400
parents beed64c7090c
children 623502678b97
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
2605
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
185
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
186 Internationalization Notes
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
187 --------------------------
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
188
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
189 How stuff works:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
190
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
191 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
192 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
193 `Marking Strings for Translation`_ section.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
194
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
195 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
196 ``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
197 Messages`_ below.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
198
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
199 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
200 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
201 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
202 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
203 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
204 message translators.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
205
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
206 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
207 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
208 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
209 See `Compiling Message Catalogs`_ section.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
210
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
211 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
212 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
213
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
214 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
215 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
216 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
217 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
218 ``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
219 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
220
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
221 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
222 module`_ documentation.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
223
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
224 `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
225 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
226 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
227
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
228 .. _GNU gettext:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
229
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
230 GNU gettext package
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
231 ~~~~~~~~~~~~~~~~~~~
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
232
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
233 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
234 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
235 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
236 for people involved in `I18N`_.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
237
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
238 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
239 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
240
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
241 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
242 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
243 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
244
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
245 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
246 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
247 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
248
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
249 Marking Strings for Translation
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2353
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 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
253 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
254
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
255 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
256 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
257
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
258 _('Index of %(classname)s') % locals()
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
259
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
260 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
261 message and, with Python formatting, remove format specifier altogether
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
262 (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
263
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
264 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
265 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
266 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
267
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
268 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
269 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
270 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
271 (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
272 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
273 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
274 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
275
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
276 Command Line Interfaces
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
277 ~~~~~~~~~~~~~~~~~~~~~~~
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
278
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
279 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
280 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
281 from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
6184
c757a6a14c8d Fix spelling of primarily.
John Rouillard <rouilj@ieee.org>
parents: 5941
diff changeset
282 ``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
283 ``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
284 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
285
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
286 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
287 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
288 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
289
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
290 from i18n import _, ngettext
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
291
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
292 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
293 message translation function ``_()``::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
294
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
295 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
296
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
297 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
298 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
299
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
300 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
301
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
302 Deferred Translations
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
303 ~~~~~~~~~~~~~~~~~~~~~
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 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
306 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
307 Example::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
308
7054
d3346c3d92f2 replace beacon with bacon in list of meal items.
John Rouillard <rouilj@ieee.org>
parents: 6836
diff changeset
309 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
310 print(_(meal))
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
311
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
312 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
313 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
314 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
315 types of string quotes::
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 strings_to_translate = (
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
318 ''"This string will be translated",
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
319 ""'me too',
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
320 ''r"\raw string",
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
321 ''"""
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
322 multiline string"""
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
323 )
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
324
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
325 .. [#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
326 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
327 as help messages.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
328
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
329 Web User Interface
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
330 ~~~~~~~~~~~~~~~~~~
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
331
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
332 For Web User Interface, translation services are provided by Client
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
333 object. Action classes have methods ``_()`` and ``gettext()``,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
334 delegating translation to the Client instance. In HTML templates,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
335 translator object is available as context variable ``i18n``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
336
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
337 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
338 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
339 (Originally documented at
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
340 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
341 which is now gone.)
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
342 Roundup translation service currently ignores values for
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
343 ``i18n:domain``, ``i18n:source`` and ``i18n:target``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
344
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
345 Template markup examples:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
346
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
347 * simplest case::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
348
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
349 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
350 Say
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
351 no
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
352 more!
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
353 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
354
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
355 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
356 trailing whitespace stripped, and inner blanks replaced with single
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
357 space character.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
358
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
359 * using variable slots::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
360
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
361 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
362 And now...<br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
363 No.<span tal:replace="number" i18n:name="slideNo" /><br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
364 THE LARCH
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
365 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
366
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
367 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
368 Template rendering will use context variable ``number`` (you may use
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
369 any expression) to put instead of ``${slideNo}`` in translation.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
370
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
371 * attribute translation::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
372
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
373 <button name="btn_wink" value=" Wink " i18n:attributes="value" />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
374
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
375 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
376
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
377 * 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
378 for the element translation explicitly, like this::
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
379
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
380 <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
381
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
382 When rendered, element contents will be replaced by translation
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
383 of the string specified in ``i18n:translate`` attribute.
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 * ``i18n`` in `TALES`_. You may translate strings in `TALES`_ python
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
386 expressions::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
387
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
388 <span tal:replace="python: i18n.gettext('Oh, wicked.')" />
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 * 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
391 You must use python expression for that::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
392
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
393 <span tal:replace="python: i18n.ngettext(
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
394 'Oh but it\'s only %i shilling.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
395 'Oh but it\'s only %i shillings.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
396 fine) % fine"
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
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
399 Detectors and extensions
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
400 ^^^^^^^^^^^^^^^^^^^^^^^^
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
401
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
402 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
403 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
404 this::
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
405
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
406 def statusfail(db, cl, nodeid, newvalues):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
407 _ = db.i18n.gettext
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
408 raise ValueError(_("this does not work"))
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
409
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
410 def init(db):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
411 # fire before changes are made
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
412 db.status.audit('create', statusfail)
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
413
7337
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
414 .. index::
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
415 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
416 see: internatonalization; i18n
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
417 see: localization; i18n
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
418
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
419 Extracting Translatable Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
420 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
421
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
422 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
423 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
424 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
425 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
426 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
427
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
428 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
429 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
430 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
431
4254
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
432 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
433 and distributed with `Roundup Source`_.
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
434 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
435 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
436 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
437 `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
438
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
439 For on-site i18n, Roundup provides command-line utility::
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 roundup-gettext <tracker_home>
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 extracting translatable messages from tracker's html templates.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
444 This utility creates message template file ``messages.pot`` in
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
445 ``locale`` subdirectory of the tracker home directory. Translated
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
446 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
447 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
448 These message catalogs are searched prior to system-wide translations
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
449 kept in the ``share`` directory.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
450
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
451 Translating Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
452 ^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
453
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
454 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
455 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
456
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
457 $ cp roundup.pot ru.po
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
458
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
459 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
460 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
461 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
462
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
463 $ msginit -i roundup.pot
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
464
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
465 ``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
466 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
467 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
468 based on current locale.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
469
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
470 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
471 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
472 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
473 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
474
3626
3e00e0110e64 removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2921
diff changeset
475 - `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
476
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
477 - `Lokalize`_. A replacement for KBabel. Being part of `KDE`_, it
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
478 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
479
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
480 - ``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
481 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
482 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
483 text mode.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
484
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
485 - `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
486 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
487 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
488 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
489 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
490 no reply so far.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
491
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
492 Compiling Message Catalogs
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
493 ^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
494
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
495 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
496 (`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
497 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
498 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
499 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
500 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
501 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
502
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
503 $ 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
504
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
505 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
506 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
507 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
508 Translatable Messages`_.)
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
510 At run time, Roundup automatically compiles message catalogs whenever
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
511 `PO`_ file is changed.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
512
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
513 .. [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
514 the Python ecosystem whenever possible.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
515
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
516
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
517
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518 .. _`Customising Roundup`: customizing.html
4949
c3a90535f7a7 Backed out changeset 4a3a35192ad1
John Rouillard <rouilj@ieee.org>
parents: 4948
diff changeset
519 .. _`Roundup's Design Document`: spec.html
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
520 .. _`implementation notes`: implementation.html
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
521
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 .. _External hyperlink targets:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
524
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
525 .. _alexander smishlajev:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
526 .. _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
527 .. _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
528 .. _copy of the mercurial repository on GitHub:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
529 https://github.com/roundup-tracker/roundup
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
530 .. _command equivalence table: https://www.mercurial-scm.org/wiki/GitConcepts#Command_equivalence_table
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
531 .. _Coveralls: https://coveralls.io/github/roundup-tracker/roundup
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
532 .. _cygwin: https://www.cygwin.com/
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
533 .. _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
534 .. _flake8: https://flake8.pycqa.org/en/latest/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
535 .. _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
536 .. _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
537 .. _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
538 .. _GNU: https://www.gnu.org/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
539 .. _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
540 .. _hosted at sourceforge:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
541 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
542 .. _issue tracker: https://issues.roundup-tracker.org/
6836
a8c757a33ab1 fix link to KDE Lokalize
John Rouillard <rouilj@ieee.org>
parents: 6658
diff changeset
543 .. _Lokalize: https://apps.kde.org/lokalize/
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
544 .. _KDE: https://kde.org/
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
545 .. _linux: https://www.linux.org/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
546 .. _Mercurial distributed version control system (DVCS):
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
547 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
548 .. _Plural Forms:
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
549 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
550 .. _po filetype plugin:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
551 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
552 .. _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
553 .. _poEdit: https://poedit.net/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
554 .. _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
555 .. _Roundup Source:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
556 .. _Roundup source distribution:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
557 .. _Roundup binary distribution:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
558 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
559 .. _roundup-devel mailing list:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
560 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
561 .. _StarterTicket on https://issues.roundup-tracker.org:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
562 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
563 .. _TAL:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
564 .. _Template Attribute Language:
5365
979390afb001 Fix some dev.zope.org links for tales and metal.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
565 https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
566 .. _TALES:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
567 .. _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
568 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
569 .. _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
570 .. _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
571 .. _ZPTInternationalization: http://grok.zope.org/doc/community/view_generation/i18n_of_your_app.html
Roundup Issue Tracker: http://roundup-tracker.org/