1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.. _podebug:
podebug
*******
Insert :wp:`pseudo translations <Pseudolocalization>` or debug markers into
target text in XLIFF, Gettex PO and other localization files.
The pseudo translation or debug markers make it easy to reference and locate
strings when your translated application is running.
Use it to:
* *Target your translations*: see what files are being referenced for string
appearing in your programs.
* *Debug translations*: if you know in what file the message occurs then you
can quickly find it and fix it.
* *Check that everything is translatable*: any English only text needs to be
analysed so that it can be localised.
* *Check for Unicode compliance*: by inserting Unicode text outside of the
Latin range it allows you to check that your program can handle non-Latin
correctly.
.. _podebug#usage:
Usage
=====
::
podebug [options] <in> <out>
Where:
+-------+----------------------------------------------------------------+
| <in> | is an input directory or localisation file |
+-------+----------------------------------------------------------------+
| <out> | is an output directory or localisation file, if missing output |
| | will be to standard out. |
+-------+----------------------------------------------------------------+
Options:
--version show program's version number and exit
-h, --help show this help message and exit
--manpage output a manpage based on the help
--progress=PROGRESS show progress as: :doc:`dots, none, bar, names,
verbose <option_progress>`
--errorlevel=ERRORLEVEL
show errorlevel as: :doc:`none, message, exception,
traceback <option_errorlevel>`
-i INPUT, --input=INPUT read from INPUT in po, pot formats
-x EXCLUDE, --exclude=EXCLUDE
exclude names matching EXCLUDE from input paths
-o OUTPUT, --output=OUTPUT
write to OUTPUT in po, pot formats
-S, --timestamp skip conversion if the output file has newer timestamp
-f FORMAT, --format=FORMAT specify format string
--rewrite=STYLE the translation rewrite style: :doc:`xxx, en, blank,
chef (v1.2), unicode (v1.2), classified (dev) <option_rewrite>`
--ignore=APPLICATION apply tagging ignore rules for the given application:
kde, gtk, openoffice, libreoffice, mozilla
--preserveplaceholders
attempt to exclude characters that are part of
placeholders when performing character-level rewrites
so that consuming applications can still use the
placeholders to generate final output
.. _podebug#formats:
Formats
=======
A format string can have these various options:
+---+----------------------------------------------------+
| f | full filename including directory |
+---+----------------------------------------------------+
| F | as %f but with .po file extension |
+---+----------------------------------------------------+
| b | base of filename |
+---+----------------------------------------------------+
| B | base of filename with .po file extension |
+---+----------------------------------------------------+
| d | directory name |
+---+----------------------------------------------------+
| s | preset OpenOffice.org modifier |
+---+----------------------------------------------------+
| c | use only consonants |
+---+----------------------------------------------------+
| h | hash value (since version 1.4 -- see notes below) |
+---+----------------------------------------------------+
| N | a set number of characters |
+---+----------------------------------------------------+
A format string may look like this:
* ``%cf`` -- the full filename without vowels
* ``[%10cb]`` -- the first ten character after compressing the base of the
filename and place it in square brackets with a space before the real message
* ``[%5cd - %cB]`` -- the first 5 consonants of the directory, followed by a
dash then the consonants of the filename with a .po extension. All
surrounded by square brackets with a space before the translations.
* ``%4h.`` -- insert a hash value of length 4
Complex format strings may make it too difficult to actually read the
translation, so you are probably best served using as short a string as
possible.
.. _podebug#rewriting_style:
Rewriting (style)
=================
The rewriting options are designed to change the target text in various ways
(c.f. the various :doc:`rewriting styles <option_rewrite>` available). This is
mostly valuable for debugging English text. The 'xxx' rewriter is useful in
that it allows you to identify text that has not localisable as that text will
lack the xxx characters.
The 'en' rewriter can be used to prepare English hashed (see below) files for
quickly finding strings that have spelling or other errors. It can also be
used to create a translated English file which can then be used for other
purposes such as British English translation.
The 'blank' rewriter strips all translations and clears fuzzy flags, useful for
starting fresh translations or creating POT templates::
podebug --rewrite=blank fr.po new-lang.po
.. _podebug#ignoring_messages:
Ignoring messages
=================
In some applications their are translations that should not be translated
(usually these are configuration options). If you do translate them then the
application will fail to compile or run.
The :opt:`--ignore` option allows you to specify the application for which you
are producing PO debug files. In this case it will then not mark certain of
the PO entries with debug messages.
In Mozilla we do not mark lone ``.accesskey``, ``.width``, ``.height``, etc
since these can really be thought of as configuration options.
.. _podebug#hashing:
Hashing
=======
Sometimes you find an error in a string. But it is difficult to search for the
occurrence of the error. In order to make it easy to find a string in your
files we can produce a hash on the strings location and other data. This
produces unique alphanumeric sequences which are prepended to the target text.
Thus now in your application you have your translated text and an alphanumeric
value. Its is then easy to search for that value and find your problem string.
.. _podebug#preserveplaceholders:
Preserving placeholders
=======================
Some translations include placeholders for variables, such as ``This is {foo}``
where changing the ``{foo}``-part would mean the translation is invalid and would
fail to compile.
The ``--preserveplaceholders`` makes sure this kind of variable names are
left intact.
.. _podebug#more_reading:
Usings podebug
==============
Here are some more examples in a `series
<http://translate.org.za/blogs/friedel/en/content/pseudolocalisation-podebug-1>`_
`of
<http://translate.org.za/blogs/friedel/en/content/pseudolocalisation-podebug-2>`_
`blog posts
<http://translate.org.za/blogs/friedel/en/content/pseudolocalisation-podebug-3-interview-rail-aliev>`_.
|
