Mercurial > p > roundup > code

annotate doc/developers.txt @ 7592:3134415ffb8a

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