1@pindex xgettext 2@cindex @code{xgettext} program, usage 3@example 4xgettext [@var{option}] [@var{inputfile}] @dots{} 5@end example 6 7The @code{xgettext} program extracts translatable strings from given 8input files. 9 10@subsection Input file location 11 12@table @samp 13@item @var{inputfile} @dots{} 14Input files. 15 16@item -f @var{file} 17@itemx --files-from=@var{file} 18@opindex -f@r{, @code{xgettext} option} 19@opindex --files-from@r{, @code{xgettext} option} 20Read the names of the input files from @var{file} instead of getting 21them from the command line. 22 23@item -D @var{directory} 24@itemx --directory=@var{directory} 25@opindex -D@r{, @code{xgettext} option} 26@opindex --directory@r{, @code{xgettext} option} 27Add @var{directory} to the list of directories. Source files are 28searched relative to this list of directories. The resulting @file{.po} 29file will be written relative to the current directory, though. 30 31@end table 32 33If @var{inputfile} is @samp{-}, standard input is read. 34 35@subsection Output file location 36 37@table @samp 38@item -d @var{name} 39@itemx --default-domain=@var{name} 40@opindex -d@r{, @code{xgettext} option} 41@opindex --default-domain@r{, @code{xgettext} option} 42Use @file{@var{name}.po} for output (instead of @file{messages.po}). 43 44@item -o @var{file} 45@itemx --output=@var{file} 46@opindex -o@r{, @code{xgettext} option} 47@opindex --output@r{, @code{xgettext} option} 48Write output to specified file (instead of @file{@var{name}.po} or 49@file{messages.po}). 50 51@item -p @var{dir} 52@itemx --output-dir=@var{dir} 53@opindex -p@r{, @code{xgettext} option} 54@opindex --output-dir@r{, @code{xgettext} option} 55Output files will be placed in directory @var{dir}. 56 57@end table 58 59@cindex output to stdout, @code{xgettext} 60If the output @var{file} is @samp{-} or @samp{/dev/stdout}, the output 61is written to standard output. 62 63@subsection Choice of input file language 64 65@table @samp 66@item -L @var{name} 67@itemx --language=@var{name} 68@opindex -L@r{, @code{xgettext} option} 69@opindex --language@r{, @code{xgettext} option} 70@cindex supported languages, @code{xgettext} 71Specifies the language of the input files. The supported languages 72are @code{C}, @code{C++}, @code{ObjectiveC}, @code{PO}, @code{Python}, 73@code{Lisp}, @code{EmacsLisp}, @code{librep}, @code{Scheme}, @code{Smalltalk}, 74@code{Java}, @code{JavaProperties}, @code{C#}, @code{awk}, @code{YCP}, 75@code{Tcl}, @code{Perl}, @code{PHP}, @code{GCC-source}, @code{NXStringTable}, 76@code{RST}, @code{Glade}. 77 78@item -C 79@itemx --c++ 80@opindex -C@r{, @code{xgettext} option} 81@opindex --c++@r{, @code{xgettext} option} 82This is a shorthand for @code{--language=C++}. 83 84@end table 85 86By default the language is guessed depending on the input file name 87extension. 88 89@subsection Input file interpretation 90 91@table @samp 92@item --from-code=@var{name} 93@opindex --from-code@r{, @code{xgettext} option} 94Specifies the encoding of the input files. This option is needed only 95if some untranslated message strings or their corresponding comments 96contain non-ASCII characters. Note that Tcl and Glade input files are 97always assumed to be in UTF-8, regardless of this option. 98 99@end table 100 101By default the input files are assumed to be in ASCII. 102 103@subsection Operation mode 104 105@table @samp 106@item -j 107@itemx --join-existing 108@opindex -j@r{, @code{xgettext} option} 109@opindex --join-existing@r{, @code{xgettext} option} 110Join messages with existing file. 111 112@item -x @var{file} 113@itemx --exclude-file=@var{file} 114@opindex -x@r{, @code{xgettext} option} 115@opindex --exclude-file@r{, @code{xgettext} option} 116Entries from @var{file} are not extracted. @var{file} should be a PO or 117POT file. 118 119@item -c [@var{tag}] 120@itemx --add-comments[=@var{tag}] 121@opindex -c@r{, @code{xgettext} option} 122@opindex --add-comments@r{, @code{xgettext} option} 123Place comment block with @var{tag} (or those preceding keyword lines) 124in output file. 125 126@end table 127 128@subsection Language specific options 129 130@table @samp 131@item -a 132@itemx --extract-all 133@opindex -a@r{, @code{xgettext} option} 134@opindex --extract-all@r{, @code{xgettext} option} 135Extract all strings. 136 137This option has an effect with most languages, namely C, C++, ObjectiveC, 138Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, 139GCC-source, Glade. 140 141@item -k @var{keywordspec} 142@itemx --keyword[=@var{keywordspec}] 143@opindex -k@r{, @code{xgettext} option} 144@opindex --keyword@r{, @code{xgettext} option} 145Additional keyword to be looked for (without @var{keywordspec} means not to 146use default keywords). 147 148@cindex adding keywords, @code{xgettext} 149@cindex context, argument specification in @code{xgettext} 150If @var{keywordspec} is a C identifier @var{id}, @code{xgettext} looks 151for strings in the first argument of each call to the function or macro 152@var{id}. If @var{keywordspec} is of the form 153@samp{@var{id}:@var{argnum}}, @code{xgettext} looks for strings in the 154@var{argnum}th argument of the call. If @var{keywordspec} is of the form 155@samp{@var{id}:@var{argnum1},@var{argnum2}}, @code{xgettext} looks for 156strings in the @var{argnum1}st argument and in the @var{argnum2}nd argument 157of the call, and treats them as singular/plural variants for a message 158with plural handling. Also, if @var{keywordspec} is of the form 159@samp{@var{id}:@var{contextargnum}c,@var{argnum}} or 160@samp{@var{id}:@var{argnum},@var{contextargnum}c}, @code{xgettext} treats 161strings in the @var{contextargnum}th argument as a context specifier. 162And, as a special-purpose support for GNOME, if @var{keywordspec} is of the 163form @samp{@var{id}:@var{argnum}g}, @code{xgettext} recognizes the 164@var{argnum}th argument as a string with context, using the GNOME @code{glib} 165syntax @samp{"msgctxt|msgid"}. 166@* 167Furthermore, if @var{keywordspec} is of the form 168@samp{@var{id}:@dots{},@var{totalnumargs}t}, @code{xgettext} recognizes this 169argument specification only if the number of actual arguments is equal to 170@var{totalnumargs}. This is useful for disambiguating overloaded function 171calls in C++. 172@* 173Finally, if @var{keywordspec} is of the form 174@samp{@var{id}:@var{argnum}...,"@var{xcomment}"}, @code{xgettext}, when 175extracting a message from the specified argument strings, adds an extracted 176comment @var{xcomment} to the message. Note that when used through a normal 177shell command line, the double-quotes around the @var{xcomment} need to be 178escaped. 179 180This option has an effect with most languages, namely C, C++, ObjectiveC, 181Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, 182GCC-source, Glade. 183 184The default keyword specifications, which are always looked for if not 185explicitly disabled, are language dependent. They are: 186 187@itemize 188@item 189For C, C++, and GCC-source: @code{gettext}, @code{dgettext:2}, 190@code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3}, 191@code{dcngettext:2,3}, @code{gettext_noop}, and @code{pgettext:1c,2}, 192@code{dpgettext:2c,3}, @code{dcpgettext:2c,3}, @code{npgettext:1c,2,3}, 193@code{dnpgettext:2c,3,4}, @code{dcnpgettext:2c,3,4}. 194 195@item 196For Objective C: Like for C, and also @code{NSLocalizedString}, @code{_}, 197@code{NSLocalizedStaticString}, @code{__}. 198 199@item 200For Shell scripts: @code{gettext}, @code{ngettext:1,2}, @code{eval_gettext}, 201@code{eval_ngettext:1,2}. 202 203@item 204For Python: @code{gettext}, @code{ugettext}, @code{dgettext:2}, 205@code{ngettext:1,2}, @code{ungettext:1,2}, @code{dngettext:2,3}, @code{_}. 206 207@item 208For Lisp: @code{gettext}, @code{ngettext:1,2}, @code{gettext-noop}. 209 210@item 211For EmacsLisp: @code{_}. 212 213@item 214For librep: @code{_}. 215 216@item 217For Scheme: @code{gettext}, @code{ngettext:1,2}, @code{gettext-noop}. 218 219@item 220For Java: @code{GettextResource.gettext:2}, 221@code{GettextResource.ngettext:2,3}, @code{GettextResource.pgettext:2c,3}, 222@code{GettextResource.npgettext:2c,3,4}, @code{gettext}, @code{ngettext:1,2}, 223@code{pgettext:1c,2}, @code{npgettext:1c,2,3}, @code{getString}. 224 225@item 226For C#: @code{GetString}, @code{GetPluralString:1,2}, 227@code{GetParticularString:1c,2}, @code{GetParticularPluralString:1c,2,3}. 228 229@item 230For awk: @code{dcgettext}, @code{dcngettext:1,2}. 231 232@item 233For Tcl: @code{::msgcat::mc}. 234 235@item 236For Perl: @code{gettext}, @code{%gettext}, @code{$gettext}, @code{dgettext:2}, 237@code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3}, 238@code{dcngettext:2,3}, @code{gettext_noop}. 239 240@item 241For PHP: @code{_}, @code{gettext}, @code{dgettext:2}, @code{dcgettext:2}, 242@code{ngettext:1,2}, @code{dngettext:2,3}, @code{dcngettext:2,3}. 243 244@item 245For Glade 1: @code{label}, @code{title}, @code{text}, @code{format}, 246@code{copyright}, @code{comments}, @code{preview_text}, @code{tooltip}. 247@end itemize 248 249To disable the default keyword specifications, the option @samp{-k} or 250@samp{--keyword} or @samp{--keyword=}, without a @var{keywordspec}, can be 251used. 252 253@item --flag=@var{word}:@var{arg}:@var{flag} 254@opindex --flag@r{, @code{xgettext} option} 255Specifies additional flags for strings occurring as part of the @var{arg}th 256argument of the function @var{word}. The possible flags are the possible 257format string indicators, such as @samp{c-format}, and their negations, 258such as @samp{no-c-format}, possibly prefixed with @samp{pass-}. 259@* 260@cindex function attribute, __format__ 261The meaning of @code{--flag=@var{function}:@var{arg}:@var{lang}-format} 262is that in language @var{lang}, the specified @var{function} expects as 263@var{arg}th argument a format string. (For those of you familiar with 264GCC function attributes, @code{--flag=@var{function}:@var{arg}:c-format} is 265roughly equivalent to the declaration 266@samp{__attribute__ ((__format__ (__printf__, @var{arg}, ...)))} attached 267to @var{function} in a C source file.) 268For example, if you use the @samp{error} function from GNU libc, you can 269specify its behaviour through @code{--flag=error:3:c-format}. The effect of 270this specification is that @code{xgettext} will mark as format strings all 271@code{gettext} invocations that occur as @var{arg}th argument of 272@var{function}. 273This is useful when such strings contain no format string directives: 274together with the checks done by @samp{msgfmt -c} it will ensure that 275translators cannot accidentally use format string directives that would 276lead to a crash at runtime. 277@* 278@cindex function attribute, __format_arg__ 279The meaning of @code{--flag=@var{function}:@var{arg}:pass-@var{lang}-format} 280is that in language @var{lang}, if the @var{function} call occurs in a 281position that must yield a format string, then its @var{arg}th argument 282must yield a format string of the same type as well. (If you know GCC 283function attributes, the @code{--flag=@var{function}:@var{arg}:pass-c-format} 284option is roughly equivalent to the declaration 285@samp{__attribute__ ((__format_arg__ (@var{arg})))} attached to @var{function} 286in a C source file.) 287For example, if you use the @samp{_} shortcut for the @code{gettext} function, 288you should use @code{--flag=_:1:pass-c-format}. The effect of this 289specification is that @code{xgettext} will propagate a format string 290requirement for a @code{_("string")} call to its first argument, the literal 291@code{"string"}, and thus mark it as a format string. 292This is useful when such strings contain no format string directives: 293together with the checks done by @samp{msgfmt -c} it will ensure that 294translators cannot accidentally use format string directives that would 295lead to a crash at runtime. 296@* 297This option has an effect with most languages, namely C, C++, ObjectiveC, 298Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP, 299GCC-source. 300 301@item -T 302@itemx --trigraphs 303@opindex -T@r{, @code{xgettext} option} 304@opindex --trigraphs@r{, @code{xgettext} option} 305@cindex C trigraphs 306Understand ANSI C trigraphs for input. 307@* 308This option has an effect only with the languages C, C++, ObjectiveC. 309 310@item --qt 311@opindex --qt@r{, @code{xgettext} option} 312@cindex Qt format strings 313Recognize Qt format strings. 314@* 315This option has an effect only with the language C++. 316 317@item --kde 318@opindex --kde@r{, @code{xgettext} option} 319@cindex KDE format strings 320Recognize KDE 4 format strings. 321@* 322This option has an effect only with the language C++. 323 324@item --boost 325@opindex --boost@r{, @code{xgettext} option} 326@cindex Boost format strings 327Recognize Boost format strings. 328@* 329This option has an effect only with the language C++. 330 331@item --debug 332@opindex --debug@r{, @code{xgettext} option} 333@cindex debugging messages marked as format strings 334Use the flags @code{c-format} and @code{possible-c-format} to show who was 335responsible for marking a message as a format string. The latter form is 336used if the @code{xgettext} program decided, the format form is used if 337the programmer prescribed it. 338 339By default only the @code{c-format} form is used. The translator should 340not have to care about these details. 341 342@end table 343 344This implementation of @code{xgettext} is able to process a few awkward 345cases, like strings in preprocessor macros, ANSI concatenation of 346adjacent strings, and escaped end of lines for continued strings. 347 348@subsection Output details 349 350@c --no-escape and --escape omitted on purpose. They are not useful. 351 352@table @samp 353@item --force-po 354@opindex --force-po@r{, @code{xgettext} option} 355Always write an output file even if no message is defined. 356 357@item -i 358@itemx --indent 359@opindex -i@r{, @code{xgettext} option} 360@opindex --indent@r{, @code{xgettext} option} 361Write the .po file using indented style. 362 363@item --no-location 364@opindex --no-location@r{, @code{xgettext} option} 365Do not write @samp{#: @var{filename}:@var{line}} lines. Note that using 366this option makes it harder for technically skilled translators to understand 367each message's context. 368 369@item -n 370@itemx --add-location 371@opindex -n@r{, @code{xgettext} option} 372@opindex --add-location@r{, @code{xgettext} option} 373Generate @samp{#: @var{filename}:@var{line}} lines (default). 374 375@item --strict 376@opindex --strict@r{, @code{xgettext} option} 377Write out a strict Uniforum conforming PO file. Note that this 378Uniforum format should be avoided because it doesn't support the 379GNU extensions. 380 381@item --properties-output 382@opindex --properties-output@r{, @code{xgettext} option} 383Write out a Java ResourceBundle in Java @code{.properties} syntax. Note 384that this file format doesn't support plural forms and silently drops 385obsolete messages. 386 387@item --stringtable-output 388@opindex --stringtable-output@r{, @code{xgettext} option} 389Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax. 390Note that this file format doesn't support plural forms. 391 392@item -w @var{number} 393@itemx --width=@var{number} 394@opindex -w@r{, @code{xgettext} option} 395@opindex --width@r{, @code{xgettext} option} 396Set the output page width. Long strings in the output files will be 397split across multiple lines in order to ensure that each line's width 398(= number of screen columns) is less or equal to the given @var{number}. 399 400@item --no-wrap 401@opindex --no-wrap@r{, @code{xgettext} option} 402Do not break long message lines. Message lines whose width exceeds the 403output page width will not be split into several lines. Only file reference 404lines which are wider than the output page width will be split. 405 406@item -s 407@itemx --sort-output 408@opindex -s@r{, @code{xgettext} option} 409@opindex --sort-output@r{, @code{xgettext} option} 410@cindex sorting output of @code{xgettext} 411Generate sorted output. Note that using this option makes it much harder 412for the translator to understand each message's context. 413 414@item -F 415@itemx --sort-by-file 416@opindex -F@r{, @code{xgettext} option} 417@opindex --sort-by-file@r{, @code{xgettext} option} 418Sort output by file location. 419 420@item --omit-header 421@opindex --omit-header@r{, @code{xgettext} option} 422Don't write header with @samp{msgid ""} entry. 423 424@cindex testing @file{.po} files for equivalence 425This is useful for testing purposes because it eliminates a source 426of variance for generated @code{.gmo} files. With @code{--omit-header}, 427two invocations of @code{xgettext} on the same files with the same 428options at different times are guaranteed to produce the same results. 429 430Note that using this option will lead to an error if the resulting file 431would not entirely be in ASCII. 432 433@item --copyright-holder=@var{string} 434@opindex --copyright-holder@r{, @code{xgettext} option} 435Set the copyright holder in the output. @var{string} should be the 436copyright holder of the surrounding package. (Note that the msgstr 437strings, extracted from the package's sources, belong to the copyright 438holder of the package.) Translators are expected to transfer or disclaim 439the copyright for their translations, so that package maintainers can 440distribute them without legal risk. If @var{string} is empty, the output 441files are marked as being in the public domain; in this case, the translators 442are expected to disclaim their copyright, again so that package maintainers 443can distribute them without legal risk. 444 445The default value for @var{string} is the Free Software Foundation, Inc., 446simply because @code{xgettext} was first used in the GNU project. 447 448@item --foreign-user 449@opindex --foreign-user@r{, @code{xgettext} option} 450Omit FSF copyright in output. This option is equivalent to 451@samp{--copyright-holder=''}. It can be useful for packages outside the GNU 452project that want their translations to be in the public domain. 453 454@item --package-name=@var{package} 455@opindex --package-name@r{, @code{xgettext} option} 456Set the package name in the header of the output. 457 458@item --package-version=@var{version} 459@opindex --package-version@r{, @code{xgettext} option} 460Set the package version in the header of the output. This option has an 461effect only if the @samp{--package-name} option is also used. 462 463@item --msgid-bugs-address=@var{email@@address} 464@opindex --msgid-bugs-address@r{, @code{xgettext} option} 465Set the reporting address for msgid bugs. This is the email address or URL 466to which the translators shall report bugs in the untranslated strings: 467 468@itemize - 469@item Strings which are not entire sentences, see the maintainer guidelines 470in @ref{Preparing Strings}. 471@item Strings which use unclear terms or require additional context to be 472understood. 473@item Strings which make invalid assumptions about notation of date, time or 474money. 475@item Pluralisation problems. 476@item Incorrect English spelling. 477@item Incorrect formatting. 478@end itemize 479 480It can be your email address, or a mailing list address where translators 481can write to without being subscribed, or the URL of a web page through 482which the translators can contact you. 483 484The default value is empty, which means that translators will be clueless! 485Don't forget to specify this option. 486 487@item -m [@var{string}] 488@itemx --msgstr-prefix[=@var{string}] 489@opindex -m@r{, @code{xgettext} option} 490@opindex --msgstr-prefix@r{, @code{xgettext} option} 491Use @var{string} (or "" if not specified) as prefix for msgstr entries. 492 493@item -M [@var{string}] 494@itemx --msgstr-suffix[=@var{string}] 495@opindex -M@r{, @code{xgettext} option} 496@opindex --msgstr-suffix@r{, @code{xgettext} option} 497Use @var{string} (or "" if not specified) as suffix for msgstr entries. 498 499@end table 500 501@subsection Informative output 502 503@table @samp 504@item -h 505@itemx --help 506@opindex -h@r{, @code{xgettext} option} 507@opindex --help@r{, @code{xgettext} option} 508Display this help and exit. 509 510@item -V 511@itemx --version 512@opindex -V@r{, @code{xgettext} option} 513@opindex --version@r{, @code{xgettext} option} 514Output version information and exit. 515 516@end table 517