3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 11 June 2016 -->
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>
255 <DT><SAMP>‘bullet-unicode’</SAMP>
257 Prefer Unicode bullet character over ASCII <CODE>*</CODE> or <CODE>-</CODE>
261 The option has an effect on all input files. To enable or disable
262 checks for a certain string, you can mark it with an <CODE>xgettext:</CODE>
263 special comment in the source file. For example, if you specify the
264 <CODE>--check=space-ellipsis</CODE> option, but want to suppress the check on
265 a particular string, add the following comment:
269 /* xgettext: no-space-ellipsis-check */
270 gettext ("We really want a space before ellipsis here ...");
273 The <CODE>xgettext:</CODE> comment can be followed by flags separated with a
274 comma. The possible flags are of the form <SAMP>‘[no-]<VAR>name</VAR>-check’</SAMP>,
275 where <VAR>name</VAR> is the name of a valid syntax check. If a flag is
276 prefixed by <CODE>no-</CODE>, the meaning is negated.
278 Some tests apply the checks to each sentence within the msgid, rather
279 than the whole string. xgettext detects the end of sentence by
280 performing a pattern match, which usually looks for a period followed by
281 a certain number of spaces. The number is specified with the
282 <CODE>--sentence-end</CODE> option.
284 <DT><SAMP>‘--sentence-end[=<VAR>TYPE</VAR>]’</SAMP>
286 <A NAME="IDX192"></A>
287 <A NAME="IDX193"></A>
288 The supported values are:
292 <DT><SAMP>‘single-space’</SAMP>
294 Expect at least one whitespace after a period
296 <DT><SAMP>‘double-space’</SAMP>
298 Expect at least two whitespaces after a period
306 <H3><A NAME="SEC34" HREF="gettext_toc.html#TOC34">5.1.6 Language specific options</A></H3>
310 <DT><SAMP>‘-a’</SAMP>
312 <DT><SAMP>‘--extract-all’</SAMP>
314 <A NAME="IDX194"></A>
315 <A NAME="IDX195"></A>
318 This option has an effect with most languages, namely C, C++, ObjectiveC,
319 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
320 GCC-source, Glade, Lua, JavaScript, Vala, GSettings.
322 <DT><SAMP>‘-k[<VAR>keywordspec</VAR>]’</SAMP>
324 <DT><SAMP>‘--keyword[=<VAR>keywordspec</VAR>]’</SAMP>
326 <A NAME="IDX196"></A>
327 <A NAME="IDX197"></A>
328 Specify <VAR>keywordspec</VAR> as an additional keyword to be looked for.
329 Without a <VAR>keywordspec</VAR>, the option means to not use default keywords.
331 <A NAME="IDX198"></A>
332 <A NAME="IDX199"></A>
333 If <VAR>keywordspec</VAR> is a C identifier <VAR>id</VAR>, <CODE>xgettext</CODE> looks
334 for strings in the first argument of each call to the function or macro
335 <VAR>id</VAR>. If <VAR>keywordspec</VAR> is of the form
336 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for strings in the
337 <VAR>argnum</VAR>th argument of the call. If <VAR>keywordspec</VAR> is of the form
338 <SAMP>‘<VAR>id</VAR>:<VAR>argnum1</VAR>,<VAR>argnum2</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for
339 strings in the <VAR>argnum1</VAR>st argument and in the <VAR>argnum2</VAR>nd argument
340 of the call, and treats them as singular/plural variants for a message
341 with plural handling. Also, if <VAR>keywordspec</VAR> is of the form
342 <SAMP>‘<VAR>id</VAR>:<VAR>contextargnum</VAR>c,<VAR>argnum</VAR>’</SAMP> or
343 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>,<VAR>contextargnum</VAR>c’</SAMP>, <CODE>xgettext</CODE> treats
344 strings in the <VAR>contextargnum</VAR>th argument as a context specifier.
345 And, as a special-purpose support for GNOME, if <VAR>keywordspec</VAR> is of the
346 form <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>g’</SAMP>, <CODE>xgettext</CODE> recognizes the
347 <VAR>argnum</VAR>th argument as a string with context, using the GNOME <CODE>glib</CODE>
348 syntax <SAMP>‘"msgctxt|msgid"’</SAMP>.
350 Furthermore, if <VAR>keywordspec</VAR> is of the form
351 <SAMP>‘<VAR>id</VAR>:...,<VAR>totalnumargs</VAR>t’</SAMP>, <CODE>xgettext</CODE> recognizes this
352 argument specification only if the number of actual arguments is equal to
353 <VAR>totalnumargs</VAR>. This is useful for disambiguating overloaded function
356 Finally, if <VAR>keywordspec</VAR> is of the form
357 <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>...,"<VAR>xcomment</VAR>"’</SAMP>, <CODE>xgettext</CODE>, when
358 extracting a message from the specified argument strings, adds an extracted
359 comment <VAR>xcomment</VAR> to the message. Note that when used through a normal
360 shell command line, the double-quotes around the <VAR>xcomment</VAR> need to be
363 This option has an effect with most languages, namely C, C++, ObjectiveC,
364 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
365 GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.
367 The default keyword specifications, which are always looked for if not
368 explicitly disabled, are language dependent. They are:
374 For C, C++, and GCC-source: <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
375 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
376 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>, and <CODE>pgettext:1c,2</CODE>,
377 <CODE>dpgettext:2c,3</CODE>, <CODE>dcpgettext:2c,3</CODE>, <CODE>npgettext:1c,2,3</CODE>,
378 <CODE>dnpgettext:2c,3,4</CODE>, <CODE>dcnpgettext:2c,3,4</CODE>.
382 For Objective C: Like for C, and also <CODE>NSLocalizedString</CODE>, <CODE>_</CODE>,
383 <CODE>NSLocalizedStaticString</CODE>, <CODE>__</CODE>.
387 For Shell scripts: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>eval_gettext</CODE>,
388 <CODE>eval_ngettext:1,2</CODE>.
392 For Python: <CODE>gettext</CODE>, <CODE>ugettext</CODE>, <CODE>dgettext:2</CODE>,
393 <CODE>ngettext:1,2</CODE>, <CODE>ungettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>_</CODE>.
397 For Lisp: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
401 For EmacsLisp: <CODE>_</CODE>.
405 For librep: <CODE>_</CODE>.
409 For Scheme: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
413 For Java: <CODE>GettextResource.gettext:2</CODE>,
414 <CODE>GettextResource.ngettext:2,3</CODE>, <CODE>GettextResource.pgettext:2c,3</CODE>,
415 <CODE>GettextResource.npgettext:2c,3,4</CODE>, <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>,
416 <CODE>pgettext:1c,2</CODE>, <CODE>npgettext:1c,2,3</CODE>, <CODE>getString</CODE>.
420 For C#: <CODE>GetString</CODE>, <CODE>GetPluralString:1,2</CODE>,
421 <CODE>GetParticularString:1c,2</CODE>, <CODE>GetParticularPluralString:1c,2,3</CODE>.
425 For awk: <CODE>dcgettext</CODE>, <CODE>dcngettext:1,2</CODE>.
429 For Tcl: <CODE>::msgcat::mc</CODE>.
433 For Perl: <CODE>gettext</CODE>, <CODE>%gettext</CODE>, <CODE>$gettext</CODE>, <CODE>dgettext:2</CODE>,
434 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
435 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>.
439 For PHP: <CODE>_</CODE>, <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>, <CODE>dcgettext:2</CODE>,
440 <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>dcngettext:2,3</CODE>.
444 For Glade 1: <CODE>label</CODE>, <CODE>title</CODE>, <CODE>text</CODE>, <CODE>format</CODE>,
445 <CODE>copyright</CODE>, <CODE>comments</CODE>, <CODE>preview_text</CODE>, <CODE>tooltip</CODE>.
449 For Lua: <CODE>_</CODE>, <CODE>gettext.gettext</CODE>, <CODE>gettext.dgettext:2</CODE>,
450 <CODE>gettext.dcgettext:2</CODE>, <CODE>gettext.ngettext:1,2</CODE>,
451 <CODE>gettext.dngettext:2,3</CODE>, <CODE>gettext.dcngettext:2,3</CODE>.
455 For JavaScript: <CODE>_</CODE>, <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
456 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
457 <CODE>pgettext:1c,2</CODE>, <CODE>dpgettext:2c,3</CODE>.
461 For Vala: <CODE>_</CODE>, <CODE>Q_</CODE>, <CODE>N_</CODE>, <CODE>NC_</CODE>, <CODE>dgettext:2</CODE>,
462 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
463 <CODE>dpgettext:2c,3</CODE>, <CODE>dpgettext2:2c,3</CODE>.
467 For Desktop: <CODE>Name</CODE>, <CODE>GenericName</CODE>, <CODE>Comment</CODE>,
468 <CODE>Icon</CODE>, <CODE>Keywords</CODE>.
471 To disable the default keyword specifications, the option <SAMP>‘-k’</SAMP> or
472 <SAMP>‘--keyword’</SAMP> or <SAMP>‘--keyword=’</SAMP>, without a <VAR>keywordspec</VAR>, can be
475 <DT><SAMP>‘--flag=<VAR>word</VAR>:<VAR>arg</VAR>:<VAR>flag</VAR>’</SAMP>
477 <A NAME="IDX200"></A>
478 Specifies additional flags for strings occurring as part of the <VAR>arg</VAR>th
479 argument of the function <VAR>word</VAR>. The possible flags are the possible
480 format string indicators, such as <SAMP>‘c-format’</SAMP>, and their negations,
481 such as <SAMP>‘no-c-format’</SAMP>, possibly prefixed with <SAMP>‘pass-’</SAMP>.
483 <A NAME="IDX201"></A>
484 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:<VAR>lang</VAR>-format</CODE>
485 is that in language <VAR>lang</VAR>, the specified <VAR>function</VAR> expects as
486 <VAR>arg</VAR>th argument a format string. (For those of you familiar with
487 GCC function attributes, <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:c-format</CODE> is
488 roughly equivalent to the declaration
489 <SAMP>‘__attribute__ ((__format__ (__printf__, <VAR>arg</VAR>, ...)))’</SAMP> attached
490 to <VAR>function</VAR> in a C source file.)
491 For example, if you use the <SAMP>‘error’</SAMP> function from GNU libc, you can
492 specify its behaviour through <CODE>--flag=error:3:c-format</CODE>. The effect of
493 this specification is that <CODE>xgettext</CODE> will mark as format strings all
494 <CODE>gettext</CODE> invocations that occur as <VAR>arg</VAR>th argument of
496 This is useful when such strings contain no format string directives:
497 together with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that
498 translators cannot accidentally use format string directives that would
499 lead to a crash at runtime.
501 <A NAME="IDX202"></A>
502 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-<VAR>lang</VAR>-format</CODE>
503 is that in language <VAR>lang</VAR>, if the <VAR>function</VAR> call occurs in a
504 position that must yield a format string, then its <VAR>arg</VAR>th argument
505 must yield a format string of the same type as well. (If you know GCC
506 function attributes, the <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-c-format</CODE>
507 option is roughly equivalent to the declaration
508 <SAMP>‘__attribute__ ((__format_arg__ (<VAR>arg</VAR>)))’</SAMP> attached to <VAR>function</VAR>
510 For example, if you use the <SAMP>‘_’</SAMP> shortcut for the <CODE>gettext</CODE> function,
511 you should use <CODE>--flag=_:1:pass-c-format</CODE>. The effect of this
512 specification is that <CODE>xgettext</CODE> will propagate a format string
513 requirement for a <CODE>_("string")</CODE> call to its first argument, the literal
514 <CODE>"string"</CODE>, and thus mark it as a format string.
515 This is useful when such strings contain no format string directives:
516 together with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that
517 translators cannot accidentally use format string directives that would
518 lead to a crash at runtime.
520 This option has an effect with most languages, namely C, C++, ObjectiveC,
521 Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
522 GCC-source, Lua, JavaScript, Vala.
524 <DT><SAMP>‘-T’</SAMP>
526 <DT><SAMP>‘--trigraphs’</SAMP>
528 <A NAME="IDX203"></A>
529 <A NAME="IDX204"></A>
530 <A NAME="IDX205"></A>
531 Understand ANSI C trigraphs for input.
533 This option has an effect only with the languages C, C++, ObjectiveC.
535 <DT><SAMP>‘--qt’</SAMP>
537 <A NAME="IDX206"></A>
538 <A NAME="IDX207"></A>
539 Recognize Qt format strings.
541 This option has an effect only with the language C++.
543 <DT><SAMP>‘--kde’</SAMP>
545 <A NAME="IDX208"></A>
546 <A NAME="IDX209"></A>
547 Recognize KDE 4 format strings.
549 This option has an effect only with the language C++.
551 <DT><SAMP>‘--boost’</SAMP>
553 <A NAME="IDX210"></A>
554 <A NAME="IDX211"></A>
555 Recognize Boost format strings.
557 This option has an effect only with the language C++.
559 <DT><SAMP>‘--debug’</SAMP>
561 <A NAME="IDX212"></A>
562 <A NAME="IDX213"></A>
563 Use the flags <CODE>c-format</CODE> and <CODE>possible-c-format</CODE> to show who was
564 responsible for marking a message as a format string. The latter form is
565 used if the <CODE>xgettext</CODE> program decided, the former form is used if
566 the programmer prescribed it.
568 By default only the <CODE>c-format</CODE> form is used. The translator should
569 not have to care about these details.
574 This implementation of <CODE>xgettext</CODE> is able to process a few awkward
575 cases, like strings in preprocessor macros, ANSI concatenation of
576 adjacent strings, and escaped end of lines for continued strings.
581 <H3><A NAME="SEC35" HREF="gettext_toc.html#TOC35">5.1.7 Output details</A></H3>
585 <DT><SAMP>‘--color’</SAMP>
587 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
589 <A NAME="IDX214"></A>
590 Specify whether or when to use colors and other text attributes.
591 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
593 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
595 <A NAME="IDX215"></A>
596 Specify the CSS style rule file to use for <CODE>--color</CODE>.
597 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
599 <DT><SAMP>‘--force-po’</SAMP>
601 <A NAME="IDX216"></A>
602 Always write an output file even if no message is defined.
604 <DT><SAMP>‘-i’</SAMP>
606 <DT><SAMP>‘--indent’</SAMP>
608 <A NAME="IDX217"></A>
609 <A NAME="IDX218"></A>
610 Write the .po file using indented style.
612 <DT><SAMP>‘--no-location’</SAMP>
614 <A NAME="IDX219"></A>
615 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. Note that using
616 this option makes it harder for technically skilled translators to understand
617 each message's context.
619 <DT><SAMP>‘-n’</SAMP>
621 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
623 <A NAME="IDX220"></A>
624 <A NAME="IDX221"></A>
625 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
627 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
628 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
629 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
630 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
631 suppresses the lines (same as <CODE>--no-location</CODE>).
633 <DT><SAMP>‘--strict’</SAMP>
635 <A NAME="IDX222"></A>
636 Write out a strict Uniforum conforming PO file. Note that this
637 Uniforum format should be avoided because it doesn't support the
640 <DT><SAMP>‘--properties-output’</SAMP>
642 <A NAME="IDX223"></A>
643 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
644 that this file format doesn't support plural forms and silently drops
647 <DT><SAMP>‘--stringtable-output’</SAMP>
649 <A NAME="IDX224"></A>
650 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
651 Note that this file format doesn't support plural forms.
653 <DT><SAMP>‘--its=<VAR>file</VAR>’</SAMP>
655 <A NAME="IDX225"></A>
656 Use ITS rules defined in <VAR>file</VAR>.
657 Note that this is only effective with XML files.
659 <DT><SAMP>‘--itstool’</SAMP>
661 <A NAME="IDX226"></A>
662 Write out comments recognized by itstool (<A HREF="http://itstool.org">http://itstool.org</A>).
663 Note that this is only effective with XML files.
665 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
667 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
669 <A NAME="IDX227"></A>
670 <A NAME="IDX228"></A>
671 Set the output page width. Long strings in the output files will be
672 split across multiple lines in order to ensure that each line's width
673 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
675 <DT><SAMP>‘--no-wrap’</SAMP>
677 <A NAME="IDX229"></A>
678 Do not break long message lines. Message lines whose width exceeds the
679 output page width will not be split into several lines. Only file reference
680 lines which are wider than the output page width will be split.
682 <DT><SAMP>‘-s’</SAMP>
684 <DT><SAMP>‘--sort-output’</SAMP>
686 <A NAME="IDX230"></A>
687 <A NAME="IDX231"></A>
688 <A NAME="IDX232"></A>
689 Generate sorted output. Note that using this option makes it much harder
690 for the translator to understand each message's context.
692 <DT><SAMP>‘-F’</SAMP>
694 <DT><SAMP>‘--sort-by-file’</SAMP>
696 <A NAME="IDX233"></A>
697 <A NAME="IDX234"></A>
698 Sort output by file location.
700 <DT><SAMP>‘--omit-header’</SAMP>
702 <A NAME="IDX235"></A>
703 Don't write header with <SAMP>‘msgid ""’</SAMP> entry.
705 <A NAME="IDX236"></A>
706 This is useful for testing purposes because it eliminates a source
707 of variance for generated <CODE>.gmo</CODE> files. With <CODE>--omit-header</CODE>,
708 two invocations of <CODE>xgettext</CODE> on the same files with the same
709 options at different times are guaranteed to produce the same results.
711 Note that using this option will lead to an error if the resulting file
712 would not entirely be in ASCII.
714 <DT><SAMP>‘--copyright-holder=<VAR>string</VAR>’</SAMP>
716 <A NAME="IDX237"></A>
717 Set the copyright holder in the output. <VAR>string</VAR> should be the
718 copyright holder of the surrounding package. (Note that the msgstr
719 strings, extracted from the package's sources, belong to the copyright
720 holder of the package.) Translators are expected to transfer or disclaim
721 the copyright for their translations, so that package maintainers can
722 distribute them without legal risk. If <VAR>string</VAR> is empty, the output
723 files are marked as being in the public domain; in this case, the translators
724 are expected to disclaim their copyright, again so that package maintainers
725 can distribute them without legal risk.
727 The default value for <VAR>string</VAR> is the Free Software Foundation, Inc.,
728 simply because <CODE>xgettext</CODE> was first used in the GNU project.
730 <DT><SAMP>‘--foreign-user’</SAMP>
732 <A NAME="IDX238"></A>
733 Omit FSF copyright in output. This option is equivalent to
734 <SAMP>‘--copyright-holder=”’</SAMP>. It can be useful for packages outside the GNU
735 project that want their translations to be in the public domain.
737 <DT><SAMP>‘--package-name=<VAR>package</VAR>’</SAMP>
739 <A NAME="IDX239"></A>
740 Set the package name in the header of the output.
742 <DT><SAMP>‘--package-version=<VAR>version</VAR>’</SAMP>
744 <A NAME="IDX240"></A>
745 Set the package version in the header of the output. This option has an
746 effect only if the <SAMP>‘--package-name’</SAMP> option is also used.
748 <DT><SAMP>‘--msgid-bugs-address=<VAR>email@address</VAR>’</SAMP>
750 <A NAME="IDX241"></A>
751 Set the reporting address for msgid bugs. This is the email address or URL
752 to which the translators shall report bugs in the untranslated strings:
756 <LI>Strings which are not entire sentences; see the maintainer guidelines
758 in section <A HREF="gettext_4.html#SEC19">4.3 Preparing Translatable Strings</A>.
759 <LI>Strings which use unclear terms or require additional context to be
762 <LI>Strings which make invalid assumptions about notation of date, time or
765 <LI>Pluralisation problems.
767 <LI>Incorrect English spelling.
769 <LI>Incorrect formatting.
773 It can be your email address, or a mailing list address where translators
774 can write to without being subscribed, or the URL of a web page through
775 which the translators can contact you.
777 The default value is empty, which means that translators will be clueless!
778 Don't forget to specify this option.
780 <DT><SAMP>‘-m[<VAR>string</VAR>]’</SAMP>
782 <DT><SAMP>‘--msgstr-prefix[=<VAR>string</VAR>]’</SAMP>
784 <A NAME="IDX242"></A>
785 <A NAME="IDX243"></A>
786 Use <VAR>string</VAR> (or "" if not specified) as prefix for msgstr values.
788 <DT><SAMP>‘-M[<VAR>string</VAR>]’</SAMP>
790 <DT><SAMP>‘--msgstr-suffix[=<VAR>string</VAR>]’</SAMP>
792 <A NAME="IDX244"></A>
793 <A NAME="IDX245"></A>
794 Use <VAR>string</VAR> (or "" if not specified) as suffix for msgstr values.
800 <H3><A NAME="SEC36" HREF="gettext_toc.html#TOC36">5.1.8 Informative output</A></H3>
804 <DT><SAMP>‘-h’</SAMP>
806 <DT><SAMP>‘--help’</SAMP>
808 <A NAME="IDX246"></A>
809 <A NAME="IDX247"></A>
810 Display this help and exit.
812 <DT><SAMP>‘-V’</SAMP>
814 <DT><SAMP>‘--version’</SAMP>
816 <A NAME="IDX248"></A>
817 <A NAME="IDX249"></A>
818 Output version information and exit.
823 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>.
projects / platform / upstream / gettext.git / blob