3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 28 December 2015 -->
6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
7 <TITLE>GNU gettext utilities - 5 Making the PO Template File</TITLE>
10 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
14 <H1><A NAME="SEC27" HREF="gettext_toc.html#TOC27">5 Making the PO Template File</A></H1>
20 After preparing the sources, the programmer creates a PO template file.
21 This section explains how to use <CODE>xgettext</CODE> for this purpose.
25 <CODE>xgettext</CODE> creates a file named <TT>‘<VAR>domainname</VAR>.po’</TT>. You
26 should then rename it to <TT>‘<VAR>domainname</VAR>.pot’</TT>. (Why doesn't
27 <CODE>xgettext</CODE> create it under the name <TT>‘<VAR>domainname</VAR>.pot’</TT>
28 right away? The answer is: for historical reasons. When <CODE>xgettext</CODE>
29 was specified, the distinction between a PO file and PO file template
30 was fuzzy, and the suffix <SAMP>‘.pot’</SAMP> wasn't in use at that time.)
36 <H2><A NAME="SEC28" HREF="gettext_toc.html#TOC28">5.1 Invoking the <CODE>xgettext</CODE> Program</A></H2>
43 xgettext [<VAR>option</VAR>] [<VAR>inputfile</VAR>] ...
47 The <CODE>xgettext</CODE> program extracts translatable strings from given
53 <H3><A NAME="SEC29" HREF="gettext_toc.html#TOC29">5.1.1 Input file location</A></H3>
57 <DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP>
61 <DT><SAMP>‘-f <VAR>file</VAR>’</SAMP>
63 <DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP>
67 Read the names of the input files from <VAR>file</VAR> instead of getting
68 them from the command line.
70 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
72 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
76 Add <VAR>directory</VAR> to the list of directories. Source files are
77 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
78 file will be written relative to the current directory, though.
83 If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read.
88 <H3><A NAME="SEC30" HREF="gettext_toc.html#TOC30">5.1.2 Output file location</A></H3>
92 <DT><SAMP>‘-d <VAR>name</VAR>’</SAMP>
94 <DT><SAMP>‘--default-domain=<VAR>name</VAR>’</SAMP>
98 Use <TT>‘<VAR>name</VAR>.po’</TT> for output (instead of <TT>‘messages.po’</TT>).
100 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
102 <DT><SAMP>‘--output=<VAR>file</VAR>’</SAMP>
104 <A NAME="IDX173"></A>
105 <A NAME="IDX174"></A>
106 Write output to specified file (instead of <TT>‘<VAR>name</VAR>.po’</TT> or
107 <TT>‘messages.po’</TT>).
109 <DT><SAMP>‘-p <VAR>dir</VAR>’</SAMP>
111 <DT><SAMP>‘--output-dir=<VAR>dir</VAR>’</SAMP>
113 <A NAME="IDX175"></A>
114 <A NAME="IDX176"></A>
115 Output files will be placed in directory <VAR>dir</VAR>.
120 <A NAME="IDX177"></A>
121 If the output <VAR>file</VAR> is <SAMP>‘-’</SAMP> or <SAMP>‘/dev/stdout’</SAMP>, the output
122 is written to standard output.
127 <H3><A NAME="SEC31" HREF="gettext_toc.html#TOC31">5.1.3 Choice of input file language</A></H3>
131 <DT><SAMP>‘-L <VAR>name</VAR>’</SAMP>
133 <DT><SAMP>‘--language=<VAR>name</VAR>’</SAMP>
135 <A NAME="IDX178"></A>
136 <A NAME="IDX179"></A>
137 <A NAME="IDX180"></A>
138 Specifies the language of the input files. The supported languages
139 are <CODE>C</CODE>, <CODE>C++</CODE>, <CODE>ObjectiveC</CODE>, <CODE>PO</CODE>, <CODE>Shell</CODE>,
140 <CODE>Python</CODE>, <CODE>Lisp</CODE>, <CODE>EmacsLisp</CODE>, <CODE>librep</CODE>, <CODE>Scheme</CODE>,
141 <CODE>Smalltalk</CODE>, <CODE>Java</CODE>, <CODE>JavaProperties</CODE>, <CODE>C#</CODE>, <CODE>awk</CODE>,
142 <CODE>YCP</CODE>, <CODE>Tcl</CODE>, <CODE>Perl</CODE>, <CODE>PHP</CODE>, <CODE>GCC-source</CODE>,
143 <CODE>NXStringTable</CODE>, <CODE>RST</CODE>, <CODE>Glade</CODE>, <CODE>Lua</CODE>, <CODE>JavaScript</CODE>,
144 <CODE>Vala</CODE>, <CODE>GSettings</CODE>, <CODE>Desktop</CODE>.
146 <DT><SAMP>‘-C’</SAMP>
148 <DT><SAMP>‘--c++’</SAMP>
150 <A NAME="IDX181"></A>
151 <A NAME="IDX182"></A>
152 This is a shorthand for <CODE>--language=C++</CODE>.
157 By default the language is guessed depending on the input file name
163 <H3><A NAME="SEC32" HREF="gettext_toc.html#TOC32">5.1.4 Input file interpretation</A></H3>
167 <DT><SAMP>‘--from-code=<VAR>name</VAR>’</SAMP>
169 <A NAME="IDX183"></A>
170 Specifies the encoding of the input files. This option is needed only
171 if some untranslated message strings or their corresponding comments
172 contain non-ASCII characters. Note that Tcl and Glade input files are
173 always assumed to be in UTF-8, regardless of this option.
178 By default the input files are assumed to be in ASCII.
183 <H3><A NAME="SEC33" HREF="gettext_toc.html#TOC33">5.1.5 Operation mode</A></H3>
187 <DT><SAMP>‘-j’</SAMP>
189 <DT><SAMP>‘--join-existing’</SAMP>
191 <A NAME="IDX184"></A>
192 <A NAME="IDX185"></A>
193 Join messages with existing file.
195 <DT><SAMP>‘-x <VAR>file</VAR>’</SAMP>
197 <DT><SAMP>‘--exclude-file=<VAR>file</VAR>’</SAMP>
199 <A NAME="IDX186"></A>
200 <A NAME="IDX187"></A>
201 Entries from <VAR>file</VAR> are not extracted. <VAR>file</VAR> should be a PO or
204 <DT><SAMP>‘-c[<VAR>tag</VAR>]’</SAMP>
206 <DT><SAMP>‘--add-comments[=<VAR>tag</VAR>]’</SAMP>
208 <A NAME="IDX188"></A>
209 <A NAME="IDX189"></A>
210 Place comment blocks starting with <VAR>tag</VAR> and preceding keyword lines
211 in the output file. Without a <VAR>tag</VAR>, the option means to put <EM>all</EM>
212 comment blocks preceding keyword lines in the output file.
214 Note that comment blocks supposed to be extracted must be adjacent to
215 keyword lines. For example, in the following C source code:
219 /* This is the first comment. */
222 /* This is the second comment: not extracted */
227 /* This is the third comment. */
231 The second comment line will not be extracted, because there is one
232 blank line between the comment line and the keyword.
234 <DT><SAMP>‘--check[=<VAR>CHECK</VAR>]’</SAMP>
236 <A NAME="IDX190"></A>
237 <A NAME="IDX191"></A>
238 Perform a syntax check on msgid and msgid_plural. The supported checks
243 <DT><SAMP>‘ellipsis-unicode’</SAMP>
245 Prefer Unicode ellipsis character over ASCII <CODE>...</CODE>
247 <DT><SAMP>‘space-ellipsis’</SAMP>
249 Prohibit whitespace before an ellipsis character
251 <DT><SAMP>‘quote-unicode’</SAMP>
253 Prefer Unicode quotation marks over ASCII <CODE>"'`</CODE>
257 The option has an effect on all input files. To enable or disable
258 checks for a certain string, you can mark it with an <CODE>xgettext:</CODE>
259 special comment in the source file. For example, if you specify the
260 <CODE>--check=space-ellipsis</CODE> option, but want to suppress the check on
261 a particular string, add the following comment:
265 /* xgettext: no-space-ellipsis-check */
266 gettext ("We really want a space before ellipsis here ...");
269 The <CODE>xgettext:</CODE> comment can be followed by flags separated with a
270 comma. The possible flags are of the form <SAMP>‘[no-]<VAR>name</VAR>-check’</SAMP>,
271 where <VAR>name</VAR> is the name of a valid syntax check. If a flag is
272 prefixed by <CODE>no-</CODE>, the meaning is negated.
274 Some tests apply the checks to each sentence within the msgid, rather
275 than the whole string. xgettext detects the end of sentence by
276 performing a pattern match, which usually looks for a period followed by
277 a certain number of spaces. The number is specified with the
278 <CODE>--sentence-end</CODE> option.
280 <DT><SAMP>‘--sentence-end[=<VAR>TYPE</VAR>]’</SAMP>
282 <A NAME="IDX192"></A>
283 <A NAME="IDX193"></A>
284 The supported values are:
288 <DT><SAMP>‘single-space’</SAMP>
290 Expect at least one whitespace after a period
292 <DT><SAMP>‘double-space’</SAMP>
294 Expect at least two whitespaces after a period
302 <H3><A NAME="SEC34" HREF="gettext_toc.html#TOC34">5.1.6 Language specific options</A></H3>
306 <DT><SAMP>‘-a’</SAMP>
308 <DT><SAMP>‘--extract-all’</SAMP>
310 <A NAME="IDX194"></A>
311 <A NAME="IDX195"></A>
314 This option has an effect with most languages, namely C, C++, ObjectiveC,
315 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
316 GCC-source, Glade, Lua, JavaScript, Vala, GSettings.
318 <DT><SAMP>‘-k[<VAR>keywordspec</VAR>]’</SAMP>
320 <DT><SAMP>‘--keyword[=<VAR>keywordspec</VAR>]’</SAMP>
322 <A NAME="IDX196"></A>
323 <A NAME="IDX197"></A>
324 Specify <VAR>keywordspec</VAR> as an additional keyword to be looked for.
325 Without a <VAR>keywordspec</VAR>, the option means to not use default keywords.
327 <A NAME="IDX198"></A>
328 <A NAME="IDX199"></A>
329 If <VAR>keywordspec</VAR> is a C identifier <VAR>id</VAR>, <CODE>xgettext</CODE> looks
330 for strings in the first argument of each call to the function or macro
331 <VAR>id</VAR>. If <VAR>keywordspec</VAR> is of the form
332 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for strings in the
333 <VAR>argnum</VAR>th argument of the call. If <VAR>keywordspec</VAR> is of the form
334 <SAMP>‘<VAR>id</VAR>:<VAR>argnum1</VAR>,<VAR>argnum2</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for
335 strings in the <VAR>argnum1</VAR>st argument and in the <VAR>argnum2</VAR>nd argument
336 of the call, and treats them as singular/plural variants for a message
337 with plural handling. Also, if <VAR>keywordspec</VAR> is of the form
338 <SAMP>‘<VAR>id</VAR>:<VAR>contextargnum</VAR>c,<VAR>argnum</VAR>’</SAMP> or
339 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>,<VAR>contextargnum</VAR>c’</SAMP>, <CODE>xgettext</CODE> treats
340 strings in the <VAR>contextargnum</VAR>th argument as a context specifier.
341 And, as a special-purpose support for GNOME, if <VAR>keywordspec</VAR> is of the
342 form <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>g’</SAMP>, <CODE>xgettext</CODE> recognizes the
343 <VAR>argnum</VAR>th argument as a string with context, using the GNOME <CODE>glib</CODE>
344 syntax <SAMP>‘"msgctxt|msgid"’</SAMP>.
346 Furthermore, if <VAR>keywordspec</VAR> is of the form
347 <SAMP>‘<VAR>id</VAR>:...,<VAR>totalnumargs</VAR>t’</SAMP>, <CODE>xgettext</CODE> recognizes this
348 argument specification only if the number of actual arguments is equal to
349 <VAR>totalnumargs</VAR>. This is useful for disambiguating overloaded function
352 Finally, if <VAR>keywordspec</VAR> is of the form
353 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>...,"<VAR>xcomment</VAR>"’</SAMP>, <CODE>xgettext</CODE>, when
354 extracting a message from the specified argument strings, adds an extracted
355 comment <VAR>xcomment</VAR> to the message. Note that when used through a normal
356 shell command line, the double-quotes around the <VAR>xcomment</VAR> need to be
359 This option has an effect with most languages, namely C, C++, ObjectiveC,
360 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
361 GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.
363 The default keyword specifications, which are always looked for if not
364 explicitly disabled, are language dependent. They are:
370 For C, C++, and GCC-source: <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
371 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
372 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>, and <CODE>pgettext:1c,2</CODE>,
373 <CODE>dpgettext:2c,3</CODE>, <CODE>dcpgettext:2c,3</CODE>, <CODE>npgettext:1c,2,3</CODE>,
374 <CODE>dnpgettext:2c,3,4</CODE>, <CODE>dcnpgettext:2c,3,4</CODE>.
378 For Objective C: Like for C, and also <CODE>NSLocalizedString</CODE>, <CODE>_</CODE>,
379 <CODE>NSLocalizedStaticString</CODE>, <CODE>__</CODE>.
383 For Shell scripts: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>eval_gettext</CODE>,
384 <CODE>eval_ngettext:1,2</CODE>.
388 For Python: <CODE>gettext</CODE>, <CODE>ugettext</CODE>, <CODE>dgettext:2</CODE>,
389 <CODE>ngettext:1,2</CODE>, <CODE>ungettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>_</CODE>.
393 For Lisp: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
397 For EmacsLisp: <CODE>_</CODE>.
401 For librep: <CODE>_</CODE>.
405 For Scheme: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
409 For Java: <CODE>GettextResource.gettext:2</CODE>,
410 <CODE>GettextResource.ngettext:2,3</CODE>, <CODE>GettextResource.pgettext:2c,3</CODE>,
411 <CODE>GettextResource.npgettext:2c,3,4</CODE>, <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>,
412 <CODE>pgettext:1c,2</CODE>, <CODE>npgettext:1c,2,3</CODE>, <CODE>getString</CODE>.
416 For C#: <CODE>GetString</CODE>, <CODE>GetPluralString:1,2</CODE>,
417 <CODE>GetParticularString:1c,2</CODE>, <CODE>GetParticularPluralString:1c,2,3</CODE>.
421 For awk: <CODE>dcgettext</CODE>, <CODE>dcngettext:1,2</CODE>.
425 For Tcl: <CODE>::msgcat::mc</CODE>.
429 For Perl: <CODE>gettext</CODE>, <CODE>%gettext</CODE>, <CODE>$gettext</CODE>, <CODE>dgettext:2</CODE>,
430 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
431 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>.
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>.
440 For Glade 1: <CODE>label</CODE>, <CODE>title</CODE>, <CODE>text</CODE>, <CODE>format</CODE>,
441 <CODE>copyright</CODE>, <CODE>comments</CODE>, <CODE>preview_text</CODE>, <CODE>tooltip</CODE>.
445 For Lua: <CODE>_</CODE>, <CODE>gettext.gettext</CODE>, <CODE>gettext.dgettext:2</CODE>,
446 <CODE>gettext.dcgettext:2</CODE>, <CODE>gettext.ngettext:1,2</CODE>,
447 <CODE>gettext.dngettext:2,3</CODE>, <CODE>gettext.dcngettext:2,3</CODE>.
451 For JavaScript: <CODE>_</CODE>, <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
452 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
453 <CODE>pgettext:1c,2</CODE>, <CODE>dpgettext:2c,3</CODE>.
457 For Vala: <CODE>_</CODE>, <CODE>Q_</CODE>, <CODE>N_</CODE>, <CODE>NC_</CODE>, <CODE>dgettext:2</CODE>,
458 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
459 <CODE>dpgettext:2c,3</CODE>, <CODE>dpgettext2:2c,3</CODE>.
463 For Desktop: <CODE>Name</CODE>, <CODE>GenericName</CODE>, <CODE>Comment</CODE>,
464 <CODE>Icon</CODE>, <CODE>Keywords</CODE>.
467 To disable the default keyword specifications, the option <SAMP>‘-k’</SAMP> or
468 <SAMP>‘--keyword’</SAMP> or <SAMP>‘--keyword=’</SAMP>, without a <VAR>keywordspec</VAR>, can be
471 <DT><SAMP>‘--flag=<VAR>word</VAR>:<VAR>arg</VAR>:<VAR>flag</VAR>’</SAMP>
473 <A NAME="IDX200"></A>
474 Specifies additional flags for strings occurring as part of the <VAR>arg</VAR>th
475 argument of the function <VAR>word</VAR>. The possible flags are the possible
476 format string indicators, such as <SAMP>‘c-format’</SAMP>, and their negations,
477 such as <SAMP>‘no-c-format’</SAMP>, possibly prefixed with <SAMP>‘pass-’</SAMP>.
479 <A NAME="IDX201"></A>
480 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:<VAR>lang</VAR>-format</CODE>
481 is that in language <VAR>lang</VAR>, the specified <VAR>function</VAR> expects as
482 <VAR>arg</VAR>th argument a format string. (For those of you familiar with
483 GCC function attributes, <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:c-format</CODE> is
484 roughly equivalent to the declaration
485 <SAMP>‘__attribute__ ((__format__ (__printf__, <VAR>arg</VAR>, ...)))’</SAMP> attached
486 to <VAR>function</VAR> in a C source file.)
487 For example, if you use the <SAMP>‘error’</SAMP> function from GNU libc, you can
488 specify its behaviour through <CODE>--flag=error:3:c-format</CODE>. The effect of
489 this specification is that <CODE>xgettext</CODE> will mark as format strings all
490 <CODE>gettext</CODE> invocations that occur as <VAR>arg</VAR>th argument of
492 This is useful when such strings contain no format string directives:
493 together with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that
494 translators cannot accidentally use format string directives that would
495 lead to a crash at runtime.
497 <A NAME="IDX202"></A>
498 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-<VAR>lang</VAR>-format</CODE>
499 is that in language <VAR>lang</VAR>, if the <VAR>function</VAR> call occurs in a
500 position that must yield a format string, then its <VAR>arg</VAR>th argument
501 must yield a format string of the same type as well. (If you know GCC
502 function attributes, the <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-c-format</CODE>
503 option is roughly equivalent to the declaration
504 <SAMP>‘__attribute__ ((__format_arg__ (<VAR>arg</VAR>)))’</SAMP> attached to <VAR>function</VAR>
506 For example, if you use the <SAMP>‘_’</SAMP> shortcut for the <CODE>gettext</CODE> function,
507 you should use <CODE>--flag=_:1:pass-c-format</CODE>. The effect of this
508 specification is that <CODE>xgettext</CODE> will propagate a format string
509 requirement for a <CODE>_("string")</CODE> call to its first argument, the literal
510 <CODE>"string"</CODE>, and thus mark it as a format string.
511 This is useful when such strings contain no format string directives:
512 together with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that
513 translators cannot accidentally use format string directives that would
514 lead to a crash at runtime.
516 This option has an effect with most languages, namely C, C++, ObjectiveC,
517 Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
518 GCC-source, Lua, JavaScript, Vala.
520 <DT><SAMP>‘-T’</SAMP>
522 <DT><SAMP>‘--trigraphs’</SAMP>
524 <A NAME="IDX203"></A>
525 <A NAME="IDX204"></A>
526 <A NAME="IDX205"></A>
527 Understand ANSI C trigraphs for input.
529 This option has an effect only with the languages C, C++, ObjectiveC.
531 <DT><SAMP>‘--qt’</SAMP>
533 <A NAME="IDX206"></A>
534 <A NAME="IDX207"></A>
535 Recognize Qt format strings.
537 This option has an effect only with the language C++.
539 <DT><SAMP>‘--kde’</SAMP>
541 <A NAME="IDX208"></A>
542 <A NAME="IDX209"></A>
543 Recognize KDE 4 format strings.
545 This option has an effect only with the language C++.
547 <DT><SAMP>‘--boost’</SAMP>
549 <A NAME="IDX210"></A>
550 <A NAME="IDX211"></A>
551 Recognize Boost format strings.
553 This option has an effect only with the language C++.
555 <DT><SAMP>‘--debug’</SAMP>
557 <A NAME="IDX212"></A>
558 <A NAME="IDX213"></A>
559 Use the flags <CODE>c-format</CODE> and <CODE>possible-c-format</CODE> to show who was
560 responsible for marking a message as a format string. The latter form is
561 used if the <CODE>xgettext</CODE> program decided, the former form is used if
562 the programmer prescribed it.
564 By default only the <CODE>c-format</CODE> form is used. The translator should
565 not have to care about these details.
570 This implementation of <CODE>xgettext</CODE> is able to process a few awkward
571 cases, like strings in preprocessor macros, ANSI concatenation of
572 adjacent strings, and escaped end of lines for continued strings.
577 <H3><A NAME="SEC35" HREF="gettext_toc.html#TOC35">5.1.7 Output details</A></H3>
581 <DT><SAMP>‘--color’</SAMP>
583 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
585 <A NAME="IDX214"></A>
586 Specify whether or when to use colors and other text attributes.
587 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
589 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
591 <A NAME="IDX215"></A>
592 Specify the CSS style rule file to use for <CODE>--color</CODE>.
593 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
595 <DT><SAMP>‘--force-po’</SAMP>
597 <A NAME="IDX216"></A>
598 Always write an output file even if no message is defined.
600 <DT><SAMP>‘-i’</SAMP>
602 <DT><SAMP>‘--indent’</SAMP>
604 <A NAME="IDX217"></A>
605 <A NAME="IDX218"></A>
606 Write the .po file using indented style.
608 <DT><SAMP>‘--no-location’</SAMP>
610 <A NAME="IDX219"></A>
611 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. Note that using
612 this option makes it harder for technically skilled translators to understand
613 each message's context.
615 <DT><SAMP>‘-n’</SAMP>
617 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
619 <A NAME="IDX220"></A>
620 <A NAME="IDX221"></A>
621 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
623 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
624 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
625 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
626 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
627 suppresses the lines (same as <CODE>--no-location</CODE>).
629 <DT><SAMP>‘--strict’</SAMP>
631 <A NAME="IDX222"></A>
632 Write out a strict Uniforum conforming PO file. Note that this
633 Uniforum format should be avoided because it doesn't support the
636 <DT><SAMP>‘--properties-output’</SAMP>
638 <A NAME="IDX223"></A>
639 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
640 that this file format doesn't support plural forms and silently drops
643 <DT><SAMP>‘--stringtable-output’</SAMP>
645 <A NAME="IDX224"></A>
646 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
647 Note that this file format doesn't support plural forms.
649 <DT><SAMP>‘--its=<VAR>file</VAR>’</SAMP>
651 <A NAME="IDX225"></A>
652 Use ITS rules defined in <VAR>file</VAR>.
653 Note that this is only effective with XML files.
655 <DT><SAMP>‘--itstool’</SAMP>
657 <A NAME="IDX226"></A>
658 Write out comments recognized by itstool (<A HREF="http://itstool.org">http://itstool.org</A>).
659 Note that this is only effective with XML files.
661 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
663 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
665 <A NAME="IDX227"></A>
666 <A NAME="IDX228"></A>
667 Set the output page width. Long strings in the output files will be
668 split across multiple lines in order to ensure that each line's width
669 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
671 <DT><SAMP>‘--no-wrap’</SAMP>
673 <A NAME="IDX229"></A>
674 Do not break long message lines. Message lines whose width exceeds the
675 output page width will not be split into several lines. Only file reference
676 lines which are wider than the output page width will be split.
678 <DT><SAMP>‘-s’</SAMP>
680 <DT><SAMP>‘--sort-output’</SAMP>
682 <A NAME="IDX230"></A>
683 <A NAME="IDX231"></A>
684 <A NAME="IDX232"></A>
685 Generate sorted output. Note that using this option makes it much harder
686 for the translator to understand each message's context.
688 <DT><SAMP>‘-F’</SAMP>
690 <DT><SAMP>‘--sort-by-file’</SAMP>
692 <A NAME="IDX233"></A>
693 <A NAME="IDX234"></A>
694 Sort output by file location.
696 <DT><SAMP>‘--omit-header’</SAMP>
698 <A NAME="IDX235"></A>
699 Don't write header with <SAMP>‘msgid ""’</SAMP> entry.
701 <A NAME="IDX236"></A>
702 This is useful for testing purposes because it eliminates a source
703 of variance for generated <CODE>.gmo</CODE> files. With <CODE>--omit-header</CODE>,
704 two invocations of <CODE>xgettext</CODE> on the same files with the same
705 options at different times are guaranteed to produce the same results.
707 Note that using this option will lead to an error if the resulting file
708 would not entirely be in ASCII.
710 <DT><SAMP>‘--copyright-holder=<VAR>string</VAR>’</SAMP>
712 <A NAME="IDX237"></A>
713 Set the copyright holder in the output. <VAR>string</VAR> should be the
714 copyright holder of the surrounding package. (Note that the msgstr
715 strings, extracted from the package's sources, belong to the copyright
716 holder of the package.) Translators are expected to transfer or disclaim
717 the copyright for their translations, so that package maintainers can
718 distribute them without legal risk. If <VAR>string</VAR> is empty, the output
719 files are marked as being in the public domain; in this case, the translators
720 are expected to disclaim their copyright, again so that package maintainers
721 can distribute them without legal risk.
723 The default value for <VAR>string</VAR> is the Free Software Foundation, Inc.,
724 simply because <CODE>xgettext</CODE> was first used in the GNU project.
726 <DT><SAMP>‘--foreign-user’</SAMP>
728 <A NAME="IDX238"></A>
729 Omit FSF copyright in output. This option is equivalent to
730 <SAMP>‘--copyright-holder=”’</SAMP>. It can be useful for packages outside the GNU
731 project that want their translations to be in the public domain.
733 <DT><SAMP>‘--package-name=<VAR>package</VAR>’</SAMP>
735 <A NAME="IDX239"></A>
736 Set the package name in the header of the output.
738 <DT><SAMP>‘--package-version=<VAR>version</VAR>’</SAMP>
740 <A NAME="IDX240"></A>
741 Set the package version in the header of the output. This option has an
742 effect only if the <SAMP>‘--package-name’</SAMP> option is also used.
744 <DT><SAMP>‘--msgid-bugs-address=<VAR>email@address</VAR>’</SAMP>
746 <A NAME="IDX241"></A>
747 Set the reporting address for msgid bugs. This is the email address or URL
748 to which the translators shall report bugs in the untranslated strings:
752 <LI>Strings which are not entire sentences; see the maintainer guidelines
754 in section <A HREF="gettext_4.html#SEC19">4.3 Preparing Translatable Strings</A>.
755 <LI>Strings which use unclear terms or require additional context to be
758 <LI>Strings which make invalid assumptions about notation of date, time or
761 <LI>Pluralisation problems.
763 <LI>Incorrect English spelling.
765 <LI>Incorrect formatting.
769 It can be your email address, or a mailing list address where translators
770 can write to without being subscribed, or the URL of a web page through
771 which the translators can contact you.
773 The default value is empty, which means that translators will be clueless!
774 Don't forget to specify this option.
776 <DT><SAMP>‘-m[<VAR>string</VAR>]’</SAMP>
778 <DT><SAMP>‘--msgstr-prefix[=<VAR>string</VAR>]’</SAMP>
780 <A NAME="IDX242"></A>
781 <A NAME="IDX243"></A>
782 Use <VAR>string</VAR> (or "" if not specified) as prefix for msgstr values.
784 <DT><SAMP>‘-M[<VAR>string</VAR>]’</SAMP>
786 <DT><SAMP>‘--msgstr-suffix[=<VAR>string</VAR>]’</SAMP>
788 <A NAME="IDX244"></A>
789 <A NAME="IDX245"></A>
790 Use <VAR>string</VAR> (or "" if not specified) as suffix for msgstr values.
796 <H3><A NAME="SEC36" HREF="gettext_toc.html#TOC36">5.1.8 Informative output</A></H3>
800 <DT><SAMP>‘-h’</SAMP>
802 <DT><SAMP>‘--help’</SAMP>
804 <A NAME="IDX246"></A>
805 <A NAME="IDX247"></A>
806 Display this help and exit.
808 <DT><SAMP>‘-V’</SAMP>
810 <DT><SAMP>‘--version’</SAMP>
812 <A NAME="IDX248"></A>
813 <A NAME="IDX249"></A>
814 Output version information and exit.
819 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.