Mercurial > p > roundup > code

annotate doc/developers.txt @ 7923:29a666d8a70d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551285 - Remove StructuredText support Asked on the users mailing list if anybody was using it. Got no responses. I have never seen CI installing structuredtext packages so it's untested as well.
author John Rouillard <rouilj@ieee.org>
date Tue, 30 Apr 2024 22:27:57 -0400
parents a363bb8c0ed4
children 828f79ae965b
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
7759
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
122 To test internationalization in your environment, you have to
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
123 process the locale sub-directory into a form that roundup's
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
124 i18n code will recognize. To do this use:
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
125
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
126 make -C locale local_install
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
127
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
128 which will compile the ``.po`` source files into binary
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
129 ``.mo`` files and install them under
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
130 ``locale/locale/<LANGUAGE_CODE>/LC_MESSAGES/roundup.mo``. For
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
131 German this will be
7874
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
132 ``locale/locale/de/LC_MESSAGES/roundup.mo``.
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
133
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
134 By default this requires ``msgfmt`` from the the GNU gettext tools
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
135 installed on your system. If you do not have ``msgfmt`` installed, you
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
136 can use:
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
137
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
138 make -C locale local_install MSGFMT="python3 ../roundup/msgfmt.py"
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
139
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
140 Also to compile a single .po file, you can invoke ``python
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
141 roundup/msgfmt.py po_file mo_file`` to compile your .po file to a .mo
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
142 file. It's slow but seems to work in basic tests. The msgfmt.py file
a363bb8c0ed4 feat: make msgfmt.py support -o flag
John Rouillard <rouilj@ieee.org>
parents: 7818
diff changeset
143 is used by Roundup to compile out of date .po files.
7759
a46675399a05 fix: make running from code tree translate strings
John Rouillard <rouilj@ieee.org>
parents: 7740
diff changeset
144
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
145 Submitting Changes
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
146 ------------------
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
147
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
148 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
149 `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
150
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
151 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
152 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
153
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
154 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
155
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
156 or
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
157
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
158 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
159
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
160 will commit your changes.
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
161
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
162
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
163 Other Resources - CI, Code Coverage
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
164 -----------------------------------
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
165
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
166 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
167 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
168 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
169 services:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
170
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
171 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
172 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
173 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
174 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
175 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
176 Python releases faster than GitHub.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
177
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
178 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
179 `Coveralls`_. TravisCI only uploads to CodeCov.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
180
7229
1dd48b540b35 Add setting up development environment section
John Rouillard <rouilj@ieee.org>
parents: 7135
diff changeset
181 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
182 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
183 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
184 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
185 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
186
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
187 Debugging Aids
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
188 --------------
6e9bd67fefa9 complete transition from HYPERDBDEBUG to new logging
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
189
7322
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
190 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
191 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
192
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
193 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
194 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
195
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
196 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
197
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
198 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
199
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
200 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
201 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
202
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
203 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
204 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
205 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
206 the python -O flag.
485cecfba982 Simplify TOC; older docs pushed a level down; Consolidate debugging
John Rouillard <rouilj@ieee.org>
parents: 7291
diff changeset
207
7740
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
208 Documentation Notes
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
209 -------------------
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
210
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
211 All docs are written using sphinx. Use pip or your package manager to
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
212 install sphinx. In addition you will need to install a couple of
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
213 sphinx extensions to process the files. A requirement's file can be
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
214 found in docs/requirement.pip or website/www/requirements.pip. You can
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
215 install these requirements using ``python -m pip install -r
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
216 <path_to_requirements_file>``.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
217
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
218 The extensions sphinx-sitemap generates a sitemap when building for
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
219 the website. The sphinx-tabs extension generates tabs for displaying
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
220 code examples in both TAL and Jinja2.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
221
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
222 To build the documentation distributed with a Roundup release, run
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
223 ``python setup.py build_doc`` at the root of the source tree. To build
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
224 docs for the website, see the ``updating www.roundup-tracker.org``
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
225 section of ``website/README.txt`` or TL;DR ``cd website/www; make
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
226 html``.
67438e439da8 docs: issue2551317 add support for jinja2 customization examples
John Rouillard <rouilj@ieee.org>
parents: 7592
diff changeset
227
7475
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
228 Testing Notes
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
229 -------------
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
230
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
231 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
232 identify test dependencies. You can do this by creating a
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
233 ``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
234 following contents::
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
235
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
236 def pytest_collection_modifyitems(items):
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
237 items.reverse()
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
238
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
239 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
240
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
241 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
242 <https://pypi.org/project/pytest-testmon/>`_ package can be installed
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
243 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
244 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
245 test suite. Use it by running::
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
246
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
247 python3 -m pytest -v --testmon test
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
248
3ff266644794 Add testing notes.
John Rouillard <rouilj@ieee.org>
parents: 7442
diff changeset
249 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
250 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
251
7592
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
252 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
253 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
254
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
255 * requests
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
256 * mock
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
257
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
258 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
259 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
260 pytest.
3134415ffb8a docs: add required modules for running tests.
John Rouillard <rouilj@ieee.org>
parents: 7475
diff changeset
261
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
262 Internationalization Notes
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
263 --------------------------
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
264
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
265 How stuff works:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
266
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
267 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
268 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
269 `Marking Strings for Translation`_ section.
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 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
272 ``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
273 Messages`_ below.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
274
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
275 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
276 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
277 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
278 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
279 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
280 message translators.
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 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
283 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
284 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
285 See `Compiling Message Catalogs`_ section.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
286
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
287 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
288 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
289
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
290 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
291 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
292 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
293 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
294 ``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
295 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
296
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
297 Additional details may be found in `GNU gettext`_ and Python `gettext
7817
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
298 module`_ documentation. Additional information on ``.po`` translation
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
299 files can also be found at pology_.
2353
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 `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
302 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
303 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
304
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
305 .. _GNU gettext:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
306
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
307 GNU gettext package
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
308 ~~~~~~~~~~~~~~~~~~~
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
309
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
310 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
311 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
312 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
313 for people involved in `I18N`_.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
314
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
315 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
316 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
317
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
318 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
319 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
320 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
321
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
322 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
323 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
324 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
325
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
326 Marking Strings for Translation
5941
29d428927362 prep for 2.0.0alpha0 release.
John Rouillard <rouilj@ieee.org>
parents: 5850
diff changeset
327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
328
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
329 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
330 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
331
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
332 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
333 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
334
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
335 _('Index of %(classname)s') % locals()
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 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
338 message and, with Python formatting, remove format specifier altogether
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
339 (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
340
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
341 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
342 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
343 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
344
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
345 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
346 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
347 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
348 (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
349 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
350 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
351 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
352
7817
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
353 Hints for the translator can be added by adding a comment block
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
354 starting with ``# .Hint``. The hints will be extracted into the .pot
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
355 file and merged to the .po files used by the translators. This can add
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
356 context to how the string is used. For example from admin.py::
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
357
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
358 # .Hint read as: assignedto was admin(1)
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
359 # where assignedto is the property
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
360 # admin is the key name for value 1
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
361 _("%(prop)s was %(name)s(%(value)s)")
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
362
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
363 is shown in the .po file as::
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
364
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
365 #. .Hint read as: assignedto was admin(1)
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
366 #. where assignedto is the property
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
367 #. admin is the key name for value 1
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
368 #: ../roundup/admin.py:1091
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
369 #, python-format
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
370 msgid "%(prop)s was %(name)s(%(value)s)"
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
371 msgstr ""
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
372
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
373 allowing the translator to see the replaced string so they can
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
374 understand how name and value are used.
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
375
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
376 Command Line Interfaces
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
377 ~~~~~~~~~~~~~~~~~~~~~~~
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
378
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
379 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
380 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
381 from Python library (``LANGUAGE``, ``LC_ALL``, ``LC_MESSAGES``, and
6184
c757a6a14c8d Fix spelling of primarily.
John Rouillard <rouilj@ieee.org>
parents: 5941
diff changeset
382 ``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
383 ``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
384 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
385
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
386 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
387 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
388 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
389
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
390 from i18n import _, ngettext
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
391
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
392 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
393 message translation function ``_()``::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
394
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
395 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
396
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
397 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
398 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
399
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5302
diff changeset
400 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
401
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
402 Deferred Translations
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
403 ~~~~~~~~~~~~~~~~~~~~~
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
404
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
405 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
406 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
407 Example::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
408
7054
d3346c3d92f2 replace beacon with bacon in list of meal items.
John Rouillard <rouilj@ieee.org>
parents: 6836
diff changeset
409 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
410 print(_(meal))
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
411
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
412 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
413 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
414 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
415 types of string quotes::
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
416
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
417 strings_to_translate = (
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
418 ''"This string will be translated",
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
419 ""'me too',
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
420 ''r"\raw string",
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
421 ''"""
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
422 multiline string"""
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
423 )
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
424
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
425 .. [#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
426 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
427 as help messages.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
428
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
429 Web User Interface
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
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
432 For Web User Interface, translation services are provided by Client
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
433 object. Action classes have methods ``_()`` and ``gettext()``,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
434 delegating translation to the Client instance. In HTML templates,
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
435 translator object is available as context variable ``i18n``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
436
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
437 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
438 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
439 (Originally documented at
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
440 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
441 which is now gone.)
cbc18a8bc61f Changes for release of version 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 6343
diff changeset
442 Roundup translation service currently ignores values for
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
443 ``i18n:domain``, ``i18n:source`` and ``i18n:target``.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
444
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
445 Template markup examples:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
446
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
447 * simplest case::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
448
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
449 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
450 Say
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
451 no
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
452 more!
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
453 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
454
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
455 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
456 trailing whitespace stripped, and inner blanks replaced with single
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
457 space character.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
458
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
459 * using variable slots::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
460
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
461 <div i18n:translate="">
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
462 And now...<br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
463 No.<span tal:replace="number" i18n:name="slideNo" /><br/>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
464 THE LARCH
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
465 </div>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
466
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
467 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
468 Template rendering will use context variable ``number`` (you may use
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
469 any expression) to put instead of ``${slideNo}`` in translation.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
470
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
471 * attribute translation::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
472
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
473 <button name="btn_wink" value=" Wink " i18n:attributes="value" />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
474
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
475 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
476
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
477 * 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
478 for the element translation explicitly, like this::
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
479
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
480 <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
481
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
482 When rendered, element contents will be replaced by translation
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
483 of the string specified in ``i18n:translate`` attribute.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
484
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
485 * ``i18n`` in `TALES`_. You may translate strings in `TALES`_ python
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
486 expressions::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
487
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
488 <span tal:replace="python: i18n.gettext('Oh, wicked.')" />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
489
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
490 * 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
491 You must use python expression for that::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
492
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
493 <span tal:replace="python: i18n.ngettext(
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
494 'Oh but it\'s only %i shilling.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
495 'Oh but it\'s only %i shillings.',
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
496 fine) % fine"
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
497 />
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
498
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
499 Detectors and extensions
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
500 ^^^^^^^^^^^^^^^^^^^^^^^^
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
501
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
502 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
503 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
504 this::
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
505
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
506 def statusfail(db, cl, nodeid, newvalues):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
507 _ = db.i18n.gettext
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
508 raise ValueError(_("this does not work"))
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
509
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
510 def init(db):
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
511 # fire before changes are made
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
512 db.status.audit('create', statusfail)
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
513
7337
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
514 .. index::
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
515 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
516 see: internatonalization; i18n
beed64c7090c Add index entry for adding translation for your tracker
John Rouillard <rouilj@ieee.org>
parents: 7322
diff changeset
517 see: localization; i18n
6658
408fd477761f Add i18n object to roundupdb.Database
Ralf Schlatterbeck <rsc@runtux.com>
parents: 6456
diff changeset
518
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
519 Extracting Translatable Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
520 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
521
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
522 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
523 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
524 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
525 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
526 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
527
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
528 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
529 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
530 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
531
4254
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
532 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
533 and distributed with `Roundup Source`_.
8d3582271a99 Minor update of doc/developers.txt...
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4228
diff changeset
534 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
535 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
536 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
537 `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
538
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
539 For on-site i18n, Roundup provides command-line utility::
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
540
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
541 roundup-gettext <tracker_home>
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
542
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
543 extracting translatable messages from tracker's html templates.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
544 This utility creates message template file ``messages.pot`` in
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
545 ``locale`` subdirectory of the tracker home directory. Translated
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
546 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
547 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
548 These message catalogs are searched prior to system-wide translations
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
549 kept in the ``share`` directory.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
550
7818
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
551 If you are creating your own ``.po`` file from scratch rather than
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
552 using ``roundup-gettext``, you must have the minimal preamble
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
553 specifying the format of the file. This::
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
554
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
555 msgid ""
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
556 msgstr ""
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
557 "Content-Type: text/plain; charset=UTF-8\n"
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
558
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
559 should be present as the first translatable string in your .po file.
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
560 If you use ``roundup-gettext`` it will add a full preamble including
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
561 ``Content-Type``. If the preamble is missing, using characters outside
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
562 of the ASCII range will cause Roundup to crash with a
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
563 UnicodeDecodeError.
a44c5da250fa doc: add specifcation of minimal header required for .po files
John Rouillard <rouilj@ieee.org>
parents: 7817
diff changeset
564
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
565 Translating Messages
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
566 ^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
567
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
568 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
569 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
570
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
571 $ cp roundup.pot ru.po
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
572
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
573 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
574 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
575 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
576
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
577 $ msginit -i roundup.pot
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
578
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
579 ``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
580 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
581 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
582 based on current locale.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
583
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
584 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
585 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
586 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
587 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
588
3626
3e00e0110e64 removed note that poEdit cannot handle plural forms - it can now
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2921
diff changeset
589 - `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
590
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
591 - `Lokalize`_. A replacement for KBabel. Being part of `KDE`_, it
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
592 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
593
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
594 - ``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
595 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
596 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
597 text mode.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
598
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
599 - `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
600 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
601 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
602 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
603 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
604 no reply so far.
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
605
7817
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
606 Additional information on ``.po`` files can be found at pology_.
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
607
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
608 Compiling Message Catalogs
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
609 ^^^^^^^^^^^^^^^^^^^^^^^^^^
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
610
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
611 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
612 (`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
613 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
614 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
615 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
616 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
617 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
618
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
619 $ 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
620
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
621 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
622 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
623 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
624 Translatable Messages`_.)
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
626 At run time, Roundup automatically compiles message catalogs whenever
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
627 `PO`_ file is changed.
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
628
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
629 .. [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
630 the Python ecosystem whenever possible.
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
631
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
632
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
633
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634 .. _`Customising Roundup`: customizing.html
4949
c3a90535f7a7 Backed out changeset 4a3a35192ad1
John Rouillard <rouilj@ieee.org>
parents: 4948
diff changeset
635 .. _`Roundup's Design Document`: spec.html
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
636 .. _`implementation notes`: implementation.html
2353
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
637
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
638
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
639 .. _External hyperlink targets:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
640
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
641 .. _alexander smishlajev:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
642 .. _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
643 .. _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
644 .. _copy of the mercurial repository on GitHub:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
645 https://github.com/roundup-tracker/roundup
7442
623502678b97 2.3.0b1 release changes
John Rouillard <rouilj@ieee.org>
parents: 7337
diff changeset
646 .. _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
647 .. _Coveralls: https://coveralls.io/github/roundup-tracker/roundup
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
648 .. _cygwin: https://www.cygwin.com/
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
649 .. _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
650 .. _flake8: https://flake8.pycqa.org/en/latest/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
651 .. _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
652 .. _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
653 .. _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
654 .. _GNU: https://www.gnu.org/
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
655 .. _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
656 .. _hosted at sourceforge:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
657 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
658 .. _issue tracker: https://issues.roundup-tracker.org/
6836
a8c757a33ab1 fix link to KDE Lokalize
John Rouillard <rouilj@ieee.org>
parents: 6658
diff changeset
659 .. _Lokalize: https://apps.kde.org/lokalize/
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
660 .. _KDE: https://kde.org/
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
661 .. _linux: https://www.linux.org/
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
662 .. _Mercurial distributed version control system (DVCS):
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
663 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
664 .. _Plural Forms:
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
665 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
666 .. _po filetype plugin:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
667 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
668 .. _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
669 .. _poEdit: https://poedit.net/
7817
161a92d1fb71 doc: link to pology; document use of .Hint extracted comments
John Rouillard <rouilj@ieee.org>
parents: 7788
diff changeset
670 .. _pology: http://pology.nedohodnik.net/doc/user/en_US/ch-poformat.html
7101
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
671 .. _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
672 .. _Roundup Source:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
673 .. _Roundup source distribution:
bf3f75134e03 i18n notes brought here from ../I18N_PROGRESS.txt
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2301
diff changeset
674 .. _Roundup binary distribution:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
675 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
676 .. _roundup-devel mailing list:
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
677 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
678 .. _StarterTicket on https://issues.roundup-tracker.org:
e4e651b1bcfa doc: add resources, spellcheck, reorder items, validate
John Rouillard <rouilj@ieee.org>
parents: 7054
diff changeset
679 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
680 .. _TAL:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
681 .. _Template Attribute Language:
5365
979390afb001 Fix some dev.zope.org links for tales and metal.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
682 https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html
2832
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
683 .. _TALES:
47766d279878 Web UI i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2605
diff changeset
684 .. _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
685 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
686 .. _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
687 .. _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
688 .. _ZPTInternationalization: http://grok.zope.org/doc/community/view_generation/i18n_of_your_app.html
Roundup Issue Tracker: http://roundup-tracker.org/