Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_5.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
2 <html>
3 <!-- Created on February, 21 2024 by texi2html 1.78a -->
4 <!--
5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6 Karl Berry <karl@freefriends.org>
7 Olaf Bachmann <obachman@mathematik.uni-kl.de>
8 and many others.
9 Maintained by: Many creative people.
10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
11
12 -->
13 <head>
14 <title>GNU gettext utilities: 5. Making the PO Template File</title>
15
16 <meta name="description" content="GNU gettext utilities: 5. Making the PO Template File">
17 <meta name="keywords" content="GNU gettext utilities: 5. Making the PO Template File">
18 <meta name="resource-type" content="document">
19 <meta name="distribution" content="global">
20 <meta name="Generator" content="texi2html 1.78a">
21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
22 <style type="text/css">
23 <!--
24 a.summary-letter {text-decoration: none}
25 pre.display {font-family: serif}
26 pre.format {font-family: serif}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 pre.smalldisplay {font-family: serif; font-size: smaller}
30 pre.smallexample {font-size: smaller}
31 pre.smallformat {font-family: serif; font-size: smaller}
32 pre.smalllisp {font-size: smaller}
33 span.roman {font-family:serif; font-weight:normal;}
34 span.sansserif {font-family:sans-serif; font-weight:normal;}
35 ul.toc {list-style: none}
36 -->
37 </style>
38
39
40 </head>
41
42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
43
44 <table cellpadding="1" cellspacing="1" border="0">
45 <tr><td valign="middle" align="left">[<a href="gettext_4.html#SEC17" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
46 <td valign="middle" align="left">[<a href="gettext_6.html#SEC45" title="Next chapter"> &gt;&gt; </a>]</td>
47 <td valign="middle" align="left"> &nbsp; </td>
48 <td valign="middle" align="left"> &nbsp; </td>
49 <td valign="middle" align="left"> &nbsp; </td>
50 <td valign="middle" align="left"> &nbsp; </td>
51 <td valign="middle" align="left"> &nbsp; </td>
52 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
53 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
54 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
55 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
56 </tr></table>
57
58 <hr size="2">
59 <a name="Template"></a>
60 <a name="SEC35"></a>
61 <h1 class="chapter"> <a href="gettext_toc.html#TOC28">5. Making the PO Template File</a> </h1>
62
63 <p>After preparing the sources, the programmer creates a PO template file.
64 This section explains how to use <code>xgettext</code> for this purpose.
65 </p>
66 <p><code>xgettext</code> creates a file named &lsquo;<tt><var>domainname</var>.po</tt>&rsquo;. You
67 should then rename it to &lsquo;<tt><var>domainname</var>.pot</tt>&rsquo;. (Why doesn't
68 <code>xgettext</code> create it under the name &lsquo;<tt><var>domainname</var>.pot</tt>&rsquo;
69 right away? The answer is: for historical reasons. When <code>xgettext</code>
70 was specified, the distinction between a PO file and PO file template
71 was fuzzy, and the suffix &lsquo;<samp>.pot</samp>&rsquo; wasn't in use at that time.)
72 </p>
73
74
75
76 <a name="xgettext-Invocation"></a>
77 <a name="SEC36"></a>
78 <h2 class="section"> <a href="gettext_toc.html#TOC29">5.1 Invoking the <code>xgettext</code> Program</a> </h2>
79
80
81 <table><tr><td>&nbsp;</td><td><pre class="example">xgettext [<var>option</var>] [<var>inputfile</var>] &hellip;
82 </pre></td></tr></table>
83
84 <p>The <code>xgettext</code> program extracts translatable strings from given
85 input files.
86 </p>
87
88 <a name="SEC37"></a>
89 <h3 class="subsection"> <a href="gettext_toc.html#TOC30">5.1.1 Input file location</a> </h3>
90
91 <dl compact="compact">
92 <dt> &lsquo;<samp><var>inputfile</var> &hellip;</samp>&rsquo;</dt>
93 <dd><p>Input files.
94 </p>
95 </dd>
96 <dt> &lsquo;<samp>-f <var>file</var></samp>&rsquo;</dt>
97 <dt> &lsquo;<samp>--files-from=<var>file</var></samp>&rsquo;</dt>
98 <dd><a name="IDX142"></a>
99 <a name="IDX143"></a>
100 <p>Read the names of the input files from <var>file</var> instead of getting
101 them from the command line.
102 </p>
103 </dd>
104 <dt> &lsquo;<samp>-D <var>directory</var></samp>&rsquo;</dt>
105 <dt> &lsquo;<samp>--directory=<var>directory</var></samp>&rsquo;</dt>
106 <dd><a name="IDX144"></a>
107 <a name="IDX145"></a>
108 <p>Add <var>directory</var> to the list of directories. Source files are
109 searched relative to this list of directories. The resulting &lsquo;<tt>.po</tt>&rsquo;
110 file will be written relative to the current directory, though.
111 </p>
112 </dd>
113 </dl>
114
115 <p>If <var>inputfile</var> is &lsquo;<samp>-</samp>&rsquo;, standard input is read.
116 </p>
117
118 <a name="SEC38"></a>
119 <h3 class="subsection"> <a href="gettext_toc.html#TOC31">5.1.2 Output file location</a> </h3>
120
121 <dl compact="compact">
122 <dt> &lsquo;<samp>-d <var>name</var></samp>&rsquo;</dt>
123 <dt> &lsquo;<samp>--default-domain=<var>name</var></samp>&rsquo;</dt>
124 <dd><a name="IDX146"></a>
125 <a name="IDX147"></a>
126 <p>Use &lsquo;<tt><var>name</var>.po</tt>&rsquo; for output (instead of &lsquo;<tt>messages.po</tt>&rsquo;).
127 </p>
128 </dd>
129 <dt> &lsquo;<samp>-o <var>file</var></samp>&rsquo;</dt>
130 <dt> &lsquo;<samp>--output=<var>file</var></samp>&rsquo;</dt>
131 <dd><a name="IDX148"></a>
132 <a name="IDX149"></a>
133 <p>Write output to specified file (instead of &lsquo;<tt><var>name</var>.po</tt>&rsquo; or
134 &lsquo;<tt>messages.po</tt>&rsquo;).
135 </p>
136 </dd>
137 <dt> &lsquo;<samp>-p <var>dir</var></samp>&rsquo;</dt>
138 <dt> &lsquo;<samp>--output-dir=<var>dir</var></samp>&rsquo;</dt>
139 <dd><a name="IDX150"></a>
140 <a name="IDX151"></a>
141 <p>Output files will be placed in directory <var>dir</var>.
142 </p>
143 </dd>
144 </dl>
145
146 <a name="IDX152"></a>
147 <p>If the output <var>file</var> is &lsquo;<samp>-</samp>&rsquo; or &lsquo;<samp>/dev/stdout</samp>&rsquo;, the output
148 is written to standard output.
149 </p>
150
151 <a name="SEC39"></a>
152 <h3 class="subsection"> <a href="gettext_toc.html#TOC32">5.1.3 Choice of input file language</a> </h3>
153
154 <dl compact="compact">
155 <dt> &lsquo;<samp>-L <var>name</var></samp>&rsquo;</dt>
156 <dt> &lsquo;<samp>--language=<var>name</var></samp>&rsquo;</dt>
157 <dd><a name="IDX153"></a>
158 <a name="IDX154"></a>
159 <a name="IDX155"></a>
160 <p>Specifies the language of the input files. The supported languages
161 are <code>C</code>, <code>C++</code>, <code>ObjectiveC</code>, <code>PO</code>, <code>Shell</code>,
162 <code>Python</code>, <code>Lisp</code>, <code>EmacsLisp</code>, <code>librep</code>, <code>Scheme</code>,
163 <code>Smalltalk</code>, <code>Java</code>, <code>JavaProperties</code>, <code>C#</code>, <code>awk</code>,
164 <code>YCP</code>, <code>Tcl</code>, <code>Perl</code>, <code>PHP</code>, <code>Ruby</code>,
165 <code>GCC-source</code>, <code>NXStringTable</code>, <code>RST</code>, <code>RSJ</code>, <code>Glade</code>,
166 <code>Lua</code>, <code>JavaScript</code>, <code>Vala</code>, <code>GSettings</code>, <code>Desktop</code>.
167 </p>
168 </dd>
169 <dt> &lsquo;<samp>-C</samp>&rsquo;</dt>
170 <dt> &lsquo;<samp>--c++</samp>&rsquo;</dt>
171 <dd><a name="IDX156"></a>
172 <a name="IDX157"></a>
173 <p>This is a shorthand for <code>--language=C++</code>.
174 </p>
175 </dd>
176 </dl>
177
178 <p>By default the language is guessed depending on the input file name
179 extension.
180 </p>
181
182 <a name="SEC40"></a>
183 <h3 class="subsection"> <a href="gettext_toc.html#TOC33">5.1.4 Input file interpretation</a> </h3>
184
185 <dl compact="compact">
186 <dt> &lsquo;<samp>--from-code=<var>name</var></samp>&rsquo;</dt>
187 <dd><a name="IDX158"></a>
188 <p>Specifies the encoding of the input files. This option is needed only
189 if some untranslated message strings or their corresponding comments
190 contain non-ASCII characters. Note that Tcl and Glade input files are
191 always assumed to be in UTF-8, regardless of this option.
192 </p>
193 </dd>
194 </dl>
195
196 <p>By default the input files are assumed to be in ASCII.
197 </p>
198
199 <a name="SEC41"></a>
200 <h3 class="subsection"> <a href="gettext_toc.html#TOC34">5.1.5 Operation mode</a> </h3>
201
202 <dl compact="compact">
203 <dt> &lsquo;<samp>-j</samp>&rsquo;</dt>
204 <dt> &lsquo;<samp>--join-existing</samp>&rsquo;</dt>
205 <dd><a name="IDX159"></a>
206 <a name="IDX160"></a>
207 <p>Join messages with existing file.
208 </p>
209 </dd>
210 <dt> &lsquo;<samp>-x <var>file</var></samp>&rsquo;</dt>
211 <dt> &lsquo;<samp>--exclude-file=<var>file</var></samp>&rsquo;</dt>
212 <dd><a name="IDX161"></a>
213 <a name="IDX162"></a>
214 <p>Entries from <var>file</var> are not extracted. <var>file</var> should be a PO or
215 POT file.
216 </p>
217 </dd>
218 <dt> &lsquo;<samp>-c[<var>tag</var>]</samp>&rsquo;</dt>
219 <dt> &lsquo;<samp>--add-comments[=<var>tag</var>]</samp>&rsquo;</dt>
220 <dd><a name="IDX163"></a>
221 <a name="IDX164"></a>
222 <p>Place comment blocks starting with <var>tag</var> and preceding keyword lines
223 in the output file. Without a <var>tag</var>, the option means to put <em>all</em>
224 comment blocks preceding keyword lines in the output file.
225 </p>
226 <p>Note that comment blocks are only extracted if there is no program code
227 between the comment and the string that gets extracted.
228 For example, in the following C source code:
229 </p>
230 <table><tr><td>&nbsp;</td><td><pre class="example">/* This is the first comment. */
231 gettext (&quot;foo&quot;);
232
233 /* This is the second comment: not extracted */
234 gettext (
235 &quot;bar&quot;);
236
237 gettext (
238 /* This is the third comment. */
239 &quot;baz&quot;);
240
241 /* This is the fourth comment. */
242
243 gettext (&quot;I love blank lines in my programs&quot;);
244 </pre></td></tr></table>
245
246 <p>the second comment line will not be extracted, because there is a line
247 with some tokens between the comment line and the line that contains
248 the string. But the fourth comment is extracted, because between it and
249 the line with the string there is merely a blank line.
250 </p>
251 </dd>
252 <dt> &lsquo;<samp>--check[=<var>CHECK</var>]</samp>&rsquo;</dt>
253 <dd><a name="IDX165"></a>
254 <a name="IDX166"></a>
255 <p>Perform a syntax check on msgid and msgid_plural. The supported checks
256 are:
257 </p>
258 <dl compact="compact">
259 <dt> &lsquo;<samp>ellipsis-unicode</samp>&rsquo;</dt>
260 <dd><p>Prefer Unicode ellipsis character over ASCII <code>...</code>
261 </p>
262 </dd>
263 <dt> &lsquo;<samp>space-ellipsis</samp>&rsquo;</dt>
264 <dd><p>Prohibit whitespace before an ellipsis character
265 </p>
266 </dd>
267 <dt> &lsquo;<samp>quote-unicode</samp>&rsquo;</dt>
268 <dd><p>Prefer Unicode quotation marks over ASCII <code>&quot;'`</code>
269 </p>
270 </dd>
271 <dt> &lsquo;<samp>bullet-unicode</samp>&rsquo;</dt>
272 <dd><p>Prefer Unicode bullet character over ASCII <code>*</code> or <code>-</code>
273 </p>
274 </dd>
275 </dl>
276
277 <p>The option has an effect on all input files. To enable or disable
278 checks for a certain string, you can mark it with an <code>xgettext:</code>
279 special comment in the source file. For example, if you specify the
280 <code>--check=space-ellipsis</code> option, but want to suppress the check on
281 a particular string, add the following comment:
282 </p>
283 <table><tr><td>&nbsp;</td><td><pre class="example">/* xgettext: no-space-ellipsis-check */
284 gettext (&quot;We really want a space before ellipsis here ...&quot;);
285 </pre></td></tr></table>
286
287 <p>The <code>xgettext:</code> comment can be followed by flags separated with a
288 comma. The possible flags are of the form &lsquo;<samp>[no-]<var>name</var>-check</samp>&rsquo;,
289 where <var>name</var> is the name of a valid syntax check. If a flag is
290 prefixed by <code>no-</code>, the meaning is negated.
291 </p>
292 <p>Some tests apply the checks to each sentence within the msgid, rather
293 than the whole string. xgettext detects the end of sentence by
294 performing a pattern match, which usually looks for a period followed by
295 a certain number of spaces. The number is specified with the
296 <code>--sentence-end</code> option.
297 </p>
298 </dd>
299 <dt> &lsquo;<samp>--sentence-end[=<var>TYPE</var>]</samp>&rsquo;</dt>
300 <dd><a name="IDX167"></a>
301 <a name="IDX168"></a>
302 <p>The supported values are:
303 </p>
304 <dl compact="compact">
305 <dt> &lsquo;<samp>single-space</samp>&rsquo;</dt>
306 <dd><p>Expect at least one whitespace after a period
307 </p>
308 </dd>
309 <dt> &lsquo;<samp>double-space</samp>&rsquo;</dt>
310 <dd><p>Expect at least two whitespaces after a period
311 </p>
312 </dd>
313 </dl>
314
315 </dd>
316 </dl>
317
318
319 <a name="SEC42"></a>
320 <h3 class="subsection"> <a href="gettext_toc.html#TOC35">5.1.6 Language specific options</a> </h3>
321
322 <dl compact="compact">
323 <dt> &lsquo;<samp>-a</samp>&rsquo;</dt>
324 <dt> &lsquo;<samp>--extract-all</samp>&rsquo;</dt>
325 <dd><a name="IDX169"></a>
326 <a name="IDX170"></a>
327 <p>Extract all strings.
328 </p>
329 <p>This option has an effect with most languages, namely C, C++, ObjectiveC,
330 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
331 GCC-source, Glade, Lua, JavaScript, Vala, GSettings.
332 </p>
333 </dd>
334 <dt> &lsquo;<samp>-k[<var>keywordspec</var>]</samp>&rsquo;</dt>
335 <dt> &lsquo;<samp>--keyword[=<var>keywordspec</var>]</samp>&rsquo;</dt>
336 <dd><a name="IDX171"></a>
337 <a name="IDX172"></a>
338 <p>Specify <var>keywordspec</var> as an additional keyword to be looked for.
339 Without a <var>keywordspec</var>, the option means to not use default keywords.
340 </p>
341 <a name="IDX173"></a>
342 <a name="IDX174"></a>
343 <p>If <var>keywordspec</var> is a C identifier <var>id</var>, <code>xgettext</code> looks
344 for strings in the first argument of each call to the function or macro
345 <var>id</var>. If <var>keywordspec</var> is of the form
346 &lsquo;<samp><var>id</var>:<var>argnum</var></samp>&rsquo;, <code>xgettext</code> looks for strings in the
347 <var>argnum</var>th argument of the call. If <var>keywordspec</var> is of the form
348 &lsquo;<samp><var>id</var>:<var>argnum1</var>,<var>argnum2</var></samp>&rsquo;, <code>xgettext</code> looks for
349 strings in the <var>argnum1</var>st argument and in the <var>argnum2</var>nd argument
350 of the call, and treats them as singular/plural variants for a message
351 with plural handling. Also, if <var>keywordspec</var> is of the form
352 &lsquo;<samp><var>id</var>:<var>contextargnum</var>c,<var>argnum</var></samp>&rsquo; or
353 &lsquo;<samp><var>id</var>:<var>argnum</var>,<var>contextargnum</var>c</samp>&rsquo;, <code>xgettext</code> treats
354 strings in the <var>contextargnum</var>th argument as a context specifier.
355 And, as a special-purpose support for GNOME, if <var>keywordspec</var> is of the
356 form &lsquo;<samp><var>id</var>:<var>argnum</var>g</samp>&rsquo;, <code>xgettext</code> recognizes the
357 <var>argnum</var>th argument as a string with context, using the GNOME <code>glib</code>
358 syntax &lsquo;<samp>&quot;msgctxt|msgid&quot;</samp>&rsquo;.
359 <br>
360 Furthermore, if <var>keywordspec</var> is of the form
361 &lsquo;<samp><var>id</var>:&hellip;,<var>totalnumargs</var>t</samp>&rsquo;, <code>xgettext</code> recognizes this
362 argument specification only if the number of actual arguments is equal to
363 <var>totalnumargs</var>. This is useful for disambiguating overloaded function
364 calls in C++.
365 <br>
366 Finally, if <var>keywordspec</var> is of the form
367 &lsquo;<samp><var>id</var>:<var>argnum</var>...,&quot;<var>xcomment</var>&quot;</samp>&rsquo;, <code>xgettext</code>, when
368 extracting a message from the specified argument strings, adds an extracted
369 comment <var>xcomment</var> to the message. Note that when used through a normal
370 shell command line, the double-quotes around the <var>xcomment</var> need to be
371 escaped.
372 </p>
373 <p>This option has an effect with most languages, namely C, C++, ObjectiveC,
374 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
375 GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.
376 </p>
377 <p>The default keyword specifications, which are always looked for if not
378 explicitly disabled, are language dependent. They are:
379 </p>
380 <ul class="toc">
381 <li>
382 For C, C++, and GCC-source: <code>gettext</code>, <code>dgettext:2</code>,
383 <code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>,
384 <code>dcngettext:2,3</code>, <code>gettext_noop</code>, and <code>pgettext:1c,2</code>,
385 <code>dpgettext:2c,3</code>, <code>dcpgettext:2c,3</code>, <code>npgettext:1c,2,3</code>,
386 <code>dnpgettext:2c,3,4</code>, <code>dcnpgettext:2c,3,4</code>.
387
388 </li><li>
389 For Objective C: Like for C, and also <code>NSLocalizedString</code>, <code>_</code>,
390 <code>NSLocalizedStaticString</code>, <code>__</code>.
391
392 </li><li>
393 For Shell scripts: <code>gettext</code>, <code>ngettext:1,2</code>, <code>eval_gettext</code>,
394 <code>eval_ngettext:1,2</code>, <code>eval_pgettext:1c,2</code>,
395 <code>eval_npgettext:1c,2,3</code>.
396
397 </li><li>
398 For Python: <code>gettext</code>, <code>ugettext</code>, <code>dgettext:2</code>,
399 <code>ngettext:1,2</code>, <code>ungettext:1,2</code>, <code>dngettext:2,3</code>, <code>_</code>.
400
401 </li><li>
402 For Lisp: <code>gettext</code>, <code>ngettext:1,2</code>, <code>gettext-noop</code>.
403
404 </li><li>
405 For EmacsLisp: <code>_</code>.
406
407 </li><li>
408 For librep: <code>_</code>.
409
410 </li><li>
411 For Scheme: <code>gettext</code>, <code>ngettext:1,2</code>, <code>gettext-noop</code>.
412
413 </li><li>
414 For Java: <code>GettextResource.gettext:2</code>,
415 <code>GettextResource.ngettext:2,3</code>, <code>GettextResource.pgettext:2c,3</code>,
416 <code>GettextResource.npgettext:2c,3,4</code>, <code>gettext</code>, <code>ngettext:1,2</code>,
417 <code>pgettext:1c,2</code>, <code>npgettext:1c,2,3</code>, <code>getString</code>.
418
419 </li><li>
420 For C#: <code>GetString</code>, <code>GetPluralString:1,2</code>,
421 <code>GetParticularString:1c,2</code>, <code>GetParticularPluralString:1c,2,3</code>.
422
423 </li><li>
424 For awk: <code>dcgettext</code>, <code>dcngettext:1,2</code>.
425
426 </li><li>
427 For Tcl: <code>::msgcat::mc</code>.
428
429 </li><li>
430 For Perl: <code>gettext</code>, <code>%gettext</code>, <code>$gettext</code>, <code>dgettext:2</code>,
431 <code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>,
432 <code>dcngettext:2,3</code>, <code>gettext_noop</code>.
433
434 </li><li>
435 For PHP: <code>_</code>, <code>gettext</code>, <code>dgettext:2</code>, <code>dcgettext:2</code>,
436 <code>ngettext:1,2</code>, <code>dngettext:2,3</code>, <code>dcngettext:2,3</code>.
437
438 </li><li>
439 For Glade 1: <code>label</code>, <code>title</code>, <code>text</code>, <code>format</code>,
440 <code>copyright</code>, <code>comments</code>, <code>preview_text</code>, <code>tooltip</code>.
441
442 </li><li>
443 For Lua: <code>_</code>, <code>gettext.gettext</code>, <code>gettext.dgettext:2</code>,
444 <code>gettext.dcgettext:2</code>, <code>gettext.ngettext:1,2</code>,
445 <code>gettext.dngettext:2,3</code>, <code>gettext.dcngettext:2,3</code>.
446
447 </li><li>
448 For JavaScript: <code>_</code>, <code>gettext</code>, <code>dgettext:2</code>,
449 <code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>,
450 <code>pgettext:1c,2</code>, <code>dpgettext:2c,3</code>.
451
452 </li><li>
453 For Vala: <code>_</code>, <code>Q_</code>, <code>N_</code>, <code>NC_</code>, <code>dgettext:2</code>,
454 <code>dcgettext:2</code>, <code>ngettext:1,2</code>, <code>dngettext:2,3</code>,
455 <code>dpgettext:2c,3</code>, <code>dpgettext2:2c,3</code>.
456
457 </li><li>
458 For Desktop: <code>Name</code>, <code>GenericName</code>, <code>Comment</code>,
459 <code>Keywords</code>.
460 </li></ul>
461
462 <p>To disable the default keyword specifications, the option &lsquo;<samp>-k</samp>&rsquo; or
463 &lsquo;<samp>--keyword</samp>&rsquo; or &lsquo;<samp>--keyword=</samp>&rsquo;, without a <var>keywordspec</var>, can be
464 used.
465 </p>
466 </dd>
467 <dt> &lsquo;<samp>--flag=<var>word</var>:<var>arg</var>:<var>flag</var></samp>&rsquo;</dt>
468 <dd><a name="IDX175"></a>
469 <p>Specifies additional flags for strings occurring as part of the <var>arg</var>th
470 argument of the function <var>word</var>. The possible flags are the possible
471 format string indicators, such as &lsquo;<samp>c-format</samp>&rsquo;, and their negations,
472 such as &lsquo;<samp>no-c-format</samp>&rsquo;, possibly prefixed with &lsquo;<samp>pass-</samp>&rsquo;.
473 <br>
474 <a name="IDX176"></a>
475 The meaning of <code>--flag=<var>function</var>:<var>arg</var>:<var>lang</var>-format</code>
476 is that in language <var>lang</var>, the specified <var>function</var> expects as
477 <var>arg</var>th argument a format string. (For those of you familiar with
478 GCC function attributes, <code>--flag=<var>function</var>:<var>arg</var>:c-format</code> is
479 roughly equivalent to the declaration
480 &lsquo;<samp>__attribute__ ((__format__ (__printf__, <var>arg</var>, ...)))</samp>&rsquo; attached
481 to <var>function</var> in a C source file.)
482 For example, if you use the &lsquo;<samp>error</samp>&rsquo; function from GNU libc, you can
483 specify its behaviour through <code>--flag=error:3:c-format</code>. The effect of
484 this specification is that <code>xgettext</code> will mark as format strings all
485 <code>gettext</code> invocations that occur as <var>arg</var>th argument of
486 <var>function</var>.
487 This is useful when such strings contain no format string directives:
488 together with the checks done by &lsquo;<samp>msgfmt -c</samp>&rsquo; it will ensure that
489 translators cannot accidentally use format string directives that would
490 lead to a crash at runtime.
491 <br>
492 <a name="IDX177"></a>
493 The meaning of <code>--flag=<var>function</var>:<var>arg</var>:pass-<var>lang</var>-format</code>
494 is that in language <var>lang</var>, if the <var>function</var> call occurs in a
495 position that must yield a format string, then its <var>arg</var>th argument
496 must yield a format string of the same type as well. (If you know GCC
497 function attributes, the <code>--flag=<var>function</var>:<var>arg</var>:pass-c-format</code>
498 option is roughly equivalent to the declaration
499 &lsquo;<samp>__attribute__ ((__format_arg__ (<var>arg</var>)))</samp>&rsquo; attached to <var>function</var>
500 in a C source file.)
501 For example, if you use the &lsquo;<samp>_</samp>&rsquo; shortcut for the <code>gettext</code> function,
502 you should use <code>--flag=_:1:pass-c-format</code>. The effect of this
503 specification is that <code>xgettext</code> will propagate a format string
504 requirement for a <code>_(&quot;string&quot;)</code> call to its first argument, the literal
505 <code>&quot;string&quot;</code>, and thus mark it as a format string.
506 This is useful when such strings contain no format string directives:
507 together with the checks done by &lsquo;<samp>msgfmt -c</samp>&rsquo; it will ensure that
508 translators cannot accidentally use format string directives that would
509 lead to a crash at runtime.
510 <br>
511 This option has an effect with most languages, namely C, C++, ObjectiveC,
512 Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
513 GCC-source, Lua, JavaScript, Vala.
514 </p>
515 </dd>
516 <dt> &lsquo;<samp>-T</samp>&rsquo;</dt>
517 <dt> &lsquo;<samp>--trigraphs</samp>&rsquo;</dt>
518 <dd><a name="IDX178"></a>
519 <a name="IDX179"></a>
520 <a name="IDX180"></a>
521 <p>Understand ANSI C trigraphs for input.
522 <br>
523 This option has an effect only with the languages C, C++, ObjectiveC.
524 </p>
525 </dd>
526 <dt> &lsquo;<samp>--qt</samp>&rsquo;</dt>
527 <dd><a name="IDX181"></a>
528 <a name="IDX182"></a>
529 <p>Recognize Qt format strings.
530 <br>
531 This option has an effect only with the language C++.
532 </p>
533 </dd>
534 <dt> &lsquo;<samp>--kde</samp>&rsquo;</dt>
535 <dd><a name="IDX183"></a>
536 <a name="IDX184"></a>
537 <p>Recognize KDE 4 format strings.
538 <br>
539 This option has an effect only with the language C++.
540 </p>
541 </dd>
542 <dt> &lsquo;<samp>--boost</samp>&rsquo;</dt>
543 <dd><a name="IDX185"></a>
544 <a name="IDX186"></a>
545 <p>Recognize Boost format strings.
546 <br>
547 This option has an effect only with the language C++.
548 </p>
549 </dd>
550 <dt> &lsquo;<samp>--debug</samp>&rsquo;</dt>
551 <dd><a name="IDX187"></a>
552 <a name="IDX188"></a>
553 <p>Use the flags <code>c-format</code> and <code>possible-c-format</code> to show who was
554 responsible for marking a message as a format string. The latter form is
555 used if the <code>xgettext</code> program decided, the former form is used if
556 the programmer prescribed it.
557 </p>
558 <p>By default only the <code>c-format</code> form is used. The translator should
559 not have to care about these details.
560 </p>
561 </dd>
562 </dl>
563
564 <p>This implementation of <code>xgettext</code> is able to process a few awkward
565 cases, like strings in preprocessor macros, ANSI concatenation of
566 adjacent strings, and escaped end of lines for continued strings.
567 </p>
568
569 <a name="SEC43"></a>
570 <h3 class="subsection"> <a href="gettext_toc.html#TOC36">5.1.7 Output details</a> </h3>
571
572
573 <dl compact="compact">
574 <dt> &lsquo;<samp>--color</samp>&rsquo;</dt>
575 <dt> &lsquo;<samp>--color=<var>when</var></samp>&rsquo;</dt>
576 <dd><a name="IDX189"></a>
577 <p>Specify whether or when to use colors and other text attributes.
578 See <a href="gettext_9.html#SEC158">The <code>--color</code> option</a> for details.
579 </p>
580 </dd>
581 <dt> &lsquo;<samp>--style=<var>style_file</var></samp>&rsquo;</dt>
582 <dd><a name="IDX190"></a>
583 <p>Specify the CSS style rule file to use for <code>--color</code>.
584 See <a href="gettext_9.html#SEC160">The <code>--style</code> option</a> for details.
585 </p>
586 </dd>
587 <dt> &lsquo;<samp>--force-po</samp>&rsquo;</dt>
588 <dd><a name="IDX191"></a>
589 <p>Always write an output file even if no message is defined.
590 </p>
591 </dd>
592 <dt> &lsquo;<samp>-i</samp>&rsquo;</dt>
593 <dt> &lsquo;<samp>--indent</samp>&rsquo;</dt>
594 <dd><a name="IDX192"></a>
595 <a name="IDX193"></a>
596 <p>Write the .po file using indented style.
597 </p>
598 </dd>
599 <dt> &lsquo;<samp>--no-location</samp>&rsquo;</dt>
600 <dd><a name="IDX194"></a>
601 <p>Do not write &lsquo;<samp>#: <var>filename</var>:<var>line</var></samp>&rsquo; lines. Note that using
602 this option makes it harder for technically skilled translators to understand
603 each message's context.
604 </p>
605 </dd>
606 <dt> &lsquo;<samp>-n</samp>&rsquo;</dt>
607 <dt> &lsquo;<samp>--add-location=<var>type</var></samp>&rsquo;</dt>
608 <dd><a name="IDX195"></a>
609 <a name="IDX196"></a>
610 <p>Generate &lsquo;<samp>#: <var>filename</var>:<var>line</var></samp>&rsquo; lines (default).
611 </p>
612 <p>The optional <var>type</var> can be either &lsquo;<samp>full</samp>&rsquo;, &lsquo;<samp>file</samp>&rsquo;, or
613 &lsquo;<samp>never</samp>&rsquo;. If it is not given or &lsquo;<samp>full</samp>&rsquo;, it generates the
614 lines with both file name and line number. If it is &lsquo;<samp>file</samp>&rsquo;, the
615 line number part is omitted. If it is &lsquo;<samp>never</samp>&rsquo;, it completely
616 suppresses the lines (same as <code>--no-location</code>).
617 </p>
618 </dd>
619 <dt> &lsquo;<samp>--strict</samp>&rsquo;</dt>
620 <dd><a name="IDX197"></a>
621 <p>Write out a strict Uniforum conforming PO file. Note that this
622 Uniforum format should be avoided because it doesn't support the
623 GNU extensions.
624 </p>
625 </dd>
626 <dt> &lsquo;<samp>--properties-output</samp>&rsquo;</dt>
627 <dd><a name="IDX198"></a>
628 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
629 that this file format doesn't support plural forms and silently drops
630 obsolete messages.
631 </p>
632 </dd>
633 <dt> &lsquo;<samp>--stringtable-output</samp>&rsquo;</dt>
634 <dd><a name="IDX199"></a>
635 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
636 Note that this file format doesn't support plural forms.
637 </p>
638 </dd>
639 <dt> &lsquo;<samp>--its=<var>file</var></samp>&rsquo;</dt>
640 <dd><a name="IDX200"></a>
641 <p>Use ITS rules defined in <var>file</var>.
642 Note that this is only effective with XML files.
643 </p>
644 </dd>
645 <dt> &lsquo;<samp>--itstool</samp>&rsquo;</dt>
646 <dd><a name="IDX201"></a>
647 <p>Write out comments recognized by itstool (<a href="http://itstool.org">http://itstool.org</a>).
648 Note that this is only effective with XML files.
649 </p>
650 </dd>
651 <dt> &lsquo;<samp>-w <var>number</var></samp>&rsquo;</dt>
652 <dt> &lsquo;<samp>--width=<var>number</var></samp>&rsquo;</dt>
653 <dd><a name="IDX202"></a>
654 <a name="IDX203"></a>
655 <p>Set the output page width. Long strings in the output files will be
656 split across multiple lines in order to ensure that each line's width
657 (= number of screen columns) is less or equal to the given <var>number</var>.
658 </p>
659 </dd>
660 <dt> &lsquo;<samp>--no-wrap</samp>&rsquo;</dt>
661 <dd><a name="IDX204"></a>
662 <p>Do not break long message lines. Message lines whose width exceeds the
663 output page width will not be split into several lines. Only file reference
664 lines which are wider than the output page width will be split.
665 </p>
666 </dd>
667 <dt> &lsquo;<samp>-s</samp>&rsquo;</dt>
668 <dt> &lsquo;<samp>--sort-output</samp>&rsquo;</dt>
669 <dd><a name="IDX205"></a>
670 <a name="IDX206"></a>
671 <a name="IDX207"></a>
672 <p>Generate sorted output (deprecated). Note that using this option makes it
673 much harder for the translator to understand each message's context.
674 </p>
675 </dd>
676 <dt> &lsquo;<samp>-F</samp>&rsquo;</dt>
677 <dt> &lsquo;<samp>--sort-by-file</samp>&rsquo;</dt>
678 <dd><a name="IDX208"></a>
679 <a name="IDX209"></a>
680 <p>Sort output by file location.
681 </p>
682 </dd>
683 <dt> &lsquo;<samp>--omit-header</samp>&rsquo;</dt>
684 <dd><a name="IDX210"></a>
685 <p>Don't write header with &lsquo;<samp>msgid &quot;&quot;</samp>&rsquo; entry.
686 </p>
687 <a name="IDX211"></a>
688 <p>This is useful for testing purposes because it eliminates a source
689 of variance for generated <code>.gmo</code> files. With <code>--omit-header</code>,
690 two invocations of <code>xgettext</code> on the same files with the same
691 options at different times are guaranteed to produce the same results.
692 </p>
693 <p>Note that using this option will lead to an error if the resulting file
694 would not entirely be in ASCII.
695 </p>
696 </dd>
697 <dt> &lsquo;<samp>--copyright-holder=<var>string</var></samp>&rsquo;</dt>
698 <dd><a name="IDX212"></a>
699 <p>Set the copyright holder in the output. <var>string</var> should be the
700 copyright holder of the surrounding package. (Note that the msgstr
701 strings, extracted from the package's sources, belong to the copyright
702 holder of the package.) Translators are expected to transfer or disclaim
703 the copyright for their translations, so that package maintainers can
704 distribute them without legal risk. If <var>string</var> is empty, the output
705 files are marked as being in the public domain; in this case, the translators
706 are expected to disclaim their copyright, again so that package maintainers
707 can distribute them without legal risk.
708 </p>
709 <p>The default value for <var>string</var> is the Free Software Foundation, Inc.,
710 simply because <code>xgettext</code> was first used in the GNU project.
711 </p>
712 </dd>
713 <dt> &lsquo;<samp>--foreign-user</samp>&rsquo;</dt>
714 <dd><a name="IDX213"></a>
715 <p>Omit FSF copyright in output. This option is equivalent to
716 &lsquo;<samp>--copyright-holder=''</samp>&rsquo;. It can be useful for packages outside the GNU
717 project that want their translations to be in the public domain.
718 </p>
719 </dd>
720 <dt> &lsquo;<samp>--package-name=<var>package</var></samp>&rsquo;</dt>
721 <dd><a name="IDX214"></a>
722 <p>Set the package name in the header of the output.
723 </p>
724 </dd>
725 <dt> &lsquo;<samp>--package-version=<var>version</var></samp>&rsquo;</dt>
726 <dd><a name="IDX215"></a>
727 <p>Set the package version in the header of the output. This option has an
728 effect only if the &lsquo;<samp>--package-name</samp>&rsquo; option is also used.
729 </p>
730 </dd>
731 <dt> &lsquo;<samp>--msgid-bugs-address=<var>email@address</var></samp>&rsquo;</dt>
732 <dd><a name="IDX216"></a>
733 <p>Set the reporting address for msgid bugs. This is the email address or URL
734 to which the translators shall report bugs in the untranslated strings:
735 </p>
736 <ul class="toc">
737 <li> - Strings which are not entire sentences; see the maintainer guidelines
738 in <a href="gettext_4.html#SEC20">Preparing Translatable Strings</a>.
739 </li><li> - Strings which use unclear terms or require additional context to be
740 understood.
741 </li><li> - Strings which make invalid assumptions about notation of date, time or
742 money.
743 </li><li> - Pluralisation problems.
744 </li><li> - Incorrect English spelling.
745 </li><li> - Incorrect formatting.
746 </li></ul>
747
748 <p>It can be your email address, or a mailing list address where translators
749 can write to without being subscribed, or the URL of a web page through
750 which the translators can contact you.
751 </p>
752 <p>The default value is empty, which means that translators will be clueless!
753 Don't forget to specify this option.
754 </p>
755 </dd>
756 <dt> &lsquo;<samp>-m[<var>string</var>]</samp>&rsquo;</dt>
757 <dt> &lsquo;<samp>--msgstr-prefix[=<var>string</var>]</samp>&rsquo;</dt>
758 <dd><a name="IDX217"></a>
759 <a name="IDX218"></a>
760 <p>Use <var>string</var> (or &quot;&quot; if not specified) as prefix for msgstr values.
761 </p>
762 </dd>
763 <dt> &lsquo;<samp>-M[<var>string</var>]</samp>&rsquo;</dt>
764 <dt> &lsquo;<samp>--msgstr-suffix[=<var>string</var>]</samp>&rsquo;</dt>
765 <dd><a name="IDX219"></a>
766 <a name="IDX220"></a>
767 <p>Use <var>string</var> (or &quot;&quot; if not specified) as suffix for msgstr values.
768 </p>
769 </dd>
770 </dl>
771
772
773 <a name="SEC44"></a>
774 <h3 class="subsection"> <a href="gettext_toc.html#TOC37">5.1.8 Informative output</a> </h3>
775
776 <dl compact="compact">
777 <dt> &lsquo;<samp>-h</samp>&rsquo;</dt>
778 <dt> &lsquo;<samp>--help</samp>&rsquo;</dt>
779 <dd><a name="IDX221"></a>
780 <a name="IDX222"></a>
781 <p>Display this help and exit.
782 </p>
783 </dd>
784 <dt> &lsquo;<samp>-V</samp>&rsquo;</dt>
785 <dt> &lsquo;<samp>--version</samp>&rsquo;</dt>
786 <dd><a name="IDX223"></a>
787 <a name="IDX224"></a>
788 <p>Output version information and exit.
789 </p>
790 </dd>
791 <dt> &lsquo;<samp>-v</samp>&rsquo;</dt>
792 <dt> &lsquo;<samp>--verbose</samp>&rsquo;</dt>
793 <dd><a name="IDX225"></a>
794 <a name="IDX226"></a>
795 <p>Increase verbosity level.
796 </p>
797 </dd>
798 </dl>
799
800
801 <table cellpadding="1" cellspacing="1" border="0">
802 <tr><td valign="middle" align="left">[<a href="#SEC35" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
803 <td valign="middle" align="left">[<a href="gettext_6.html#SEC45" title="Next chapter"> &gt;&gt; </a>]</td>
804 <td valign="middle" align="left"> &nbsp; </td>
805 <td valign="middle" align="left"> &nbsp; </td>
806 <td valign="middle" align="left"> &nbsp; </td>
807 <td valign="middle" align="left"> &nbsp; </td>
808 <td valign="middle" align="left"> &nbsp; </td>
809 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
810 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
811 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
812 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
813 </tr></table>
814 <p>
815 <font size="-1">
816 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
817 </font>
818 <br>
819
820 </p>
821 </body>
822 </html>