gettext: xgettext Invocation
1
1 5.1 Invoking the ‘xgettext’ Program
1 ===================================
1
1 xgettext [OPTION] [INPUTFILE] …
1
1 The ‘xgettext’ program extracts translatable strings from given input
1 files.
1
1 5.1.1 Input file location
1 -------------------------
1
1 ‘INPUTFILE …’
1 Input files.
1
1 ‘-f FILE’
1 ‘--files-from=FILE’
1 Read the names of the input files from FILE instead of getting them
1 from the command line.
1
1 ‘-D DIRECTORY’
1 ‘--directory=DIRECTORY’
1 Add DIRECTORY to the list of directories. Source files are
1 searched relative to this list of directories. The resulting ‘.po’
1 file will be written relative to the current directory, though.
1
1 If INPUTFILE is ‘-’, standard input is read.
1
1 5.1.2 Output file location
1 --------------------------
1
1 ‘-d NAME’
1 ‘--default-domain=NAME’
1 Use ‘NAME.po’ for output (instead of ‘messages.po’).
1
1 ‘-o FILE’
1 ‘--output=FILE’
1 Write output to specified file (instead of ‘NAME.po’ or
1 ‘messages.po’).
1
1 ‘-p DIR’
1 ‘--output-dir=DIR’
1 Output files will be placed in directory DIR.
1
1 If the output FILE is ‘-’ or ‘/dev/stdout’, the output is written to
1 standard output.
1
1 5.1.3 Choice of input file language
1 -----------------------------------
1
1 ‘-L NAME’
1 ‘--language=NAME’
1 Specifies the language of the input files. The supported languages
1 are ‘C’, ‘C++’, ‘ObjectiveC’, ‘PO’, ‘Shell’, ‘Python’, ‘Lisp’,
1 ‘EmacsLisp’, ‘librep’, ‘Scheme’, ‘Smalltalk’, ‘Java’,
1 ‘JavaProperties’, ‘C#’, ‘awk’, ‘YCP’, ‘Tcl’, ‘Perl’, ‘PHP’,
1 ‘GCC-source’, ‘NXStringTable’, ‘RST’, ‘Glade’, ‘Lua’, ‘JavaScript’,
1 ‘Vala’, ‘GSettings’, ‘Desktop’.
1
1 ‘-C’
1 ‘--c++’
1 This is a shorthand for ‘--language=C++’.
1
1 By default the language is guessed depending on the input file name
1 extension.
1
1 5.1.4 Input file interpretation
1 -------------------------------
1
1 ‘--from-code=NAME’
1 Specifies the encoding of the input files. This option is needed
1 only if some untranslated message strings or their corresponding
1 comments contain non-ASCII characters. Note that Tcl and Glade
1 input files are always assumed to be in UTF-8, regardless of this
1 option.
1
1 By default the input files are assumed to be in ASCII.
1
1 5.1.5 Operation mode
1 --------------------
1
1 ‘-j’
1 ‘--join-existing’
1 Join messages with existing file.
1
1 ‘-x FILE’
1 ‘--exclude-file=FILE’
1 Entries from FILE are not extracted. FILE should be a PO or POT
1 file.
1
1 ‘-c[TAG]’
1 ‘--add-comments[=TAG]’
1 Place comment blocks starting with TAG and preceding keyword lines
1 in the output file. Without a TAG, the option means to put _all_
1 comment blocks preceding keyword lines in the output file.
1
1 Note that comment blocks supposed to be extracted must be adjacent
1 to keyword lines. For example, in the following C source code:
1
1 /* This is the first comment. */
1 gettext ("foo");
1
1 /* This is the second comment: not extracted */
1 gettext (
1 "bar");
1
1 gettext (
1 /* This is the third comment. */
1 "baz");
1
1 The second comment line will not be extracted, because there is one
1 blank line between the comment line and the keyword.
1
1 ‘--check[=CHECK]’
1 Perform a syntax check on msgid and msgid_plural. The supported
1 checks are:
1
1 ‘ellipsis-unicode’
1 Prefer Unicode ellipsis character over ASCII ‘...’
1
1 ‘space-ellipsis’
1 Prohibit whitespace before an ellipsis character
1
1 ‘quote-unicode’
1 Prefer Unicode quotation marks over ASCII ‘"'`’
1
1 ‘bullet-unicode’
1 Prefer Unicode bullet character over ASCII ‘*’ or ‘-’
1
1 The option has an effect on all input files. To enable or disable
1 checks for a certain string, you can mark it with an ‘xgettext:’
1 special comment in the source file. For example, if you specify
1 the ‘--check=space-ellipsis’ option, but want to suppress the check
1 on a particular string, add the following comment:
1
1 /* xgettext: no-space-ellipsis-check */
1 gettext ("We really want a space before ellipsis here ...");
1
1 The ‘xgettext:’ comment can be followed by flags separated with a
1 comma. The possible flags are of the form ‘[no-]NAME-check’, where
1 NAME is the name of a valid syntax check. If a flag is prefixed by
1 ‘no-’, the meaning is negated.
1
1 Some tests apply the checks to each sentence within the msgid,
1 rather than the whole string. xgettext detects the end of sentence
1 by performing a pattern match, which usually looks for a period
1 followed by a certain number of spaces. The number is specified
1 with the ‘--sentence-end’ option.
1
1 ‘--sentence-end[=TYPE]’
1 The supported values are:
1
1 ‘single-space’
1 Expect at least one whitespace after a period
1
1 ‘double-space’
1 Expect at least two whitespaces after a period
1
1 5.1.6 Language specific options
1 -------------------------------
1
1 ‘-a’
1 ‘--extract-all’
1 Extract all strings.
1
1 This option has an effect with most languages, namely C, C++,
1 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
1 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
1 GSettings.
1
1 ‘-k[KEYWORDSPEC]’
1 ‘--keyword[=KEYWORDSPEC]’
1 Specify KEYWORDSPEC as an additional keyword to be looked for.
1 Without a KEYWORDSPEC, the option means to not use default
1 keywords.
1
1 If KEYWORDSPEC is a C identifier ID, ‘xgettext’ looks for strings
1 in the first argument of each call to the function or macro ID. If
1 KEYWORDSPEC is of the form ‘ID:ARGNUM’, ‘xgettext’ looks for
1 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is of
1 the form ‘ID:ARGNUM1,ARGNUM2’, ‘xgettext’ looks for strings in the
1 ARGNUM1st argument and in the ARGNUM2nd argument of the call, and
1 treats them as singular/plural variants for a message with plural
1 handling. Also, if KEYWORDSPEC is of the form
1 ‘ID:CONTEXTARGNUMc,ARGNUM’ or ‘ID:ARGNUM,CONTEXTARGNUMc’,
1 ‘xgettext’ treats strings in the CONTEXTARGNUMth argument as a
1 context specifier. And, as a special-purpose support for GNOME, if
1 KEYWORDSPEC is of the form ‘ID:ARGNUMg’, ‘xgettext’ recognizes the
1 ARGNUMth argument as a string with context, using the GNOME ‘glib’
1 syntax ‘"msgctxt|msgid"’.
1 Furthermore, if KEYWORDSPEC is of the form ‘ID:…,TOTALNUMARGSt’,
1 ‘xgettext’ recognizes this argument specification only if the
1 number of actual arguments is equal to TOTALNUMARGS. This is
1 useful for disambiguating overloaded function calls in C++.
1 Finally, if KEYWORDSPEC is of the form ‘ID:ARGNUM...,"XCOMMENT"’,
1 ‘xgettext’, when extracting a message from the specified argument
1 strings, adds an extracted comment XCOMMENT to the message. Note
1 that when used through a normal shell command line, the
1 double-quotes around the XCOMMENT need to be escaped.
1
1 This option has an effect with most languages, namely C, C++,
1 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
1 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
1 GSettings, Desktop.
1
1 The default keyword specifications, which are always looked for if
1 not explicitly disabled, are language dependent. They are:
1
1 • For C, C++, and GCC-source: ‘gettext’, ‘dgettext:2’,
1 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
1 ‘dcngettext:2,3’, ‘gettext_noop’, and ‘pgettext:1c,2’,
1 ‘dpgettext:2c,3’, ‘dcpgettext:2c,3’, ‘npgettext:1c,2,3’,
1 ‘dnpgettext:2c,3,4’, ‘dcnpgettext:2c,3,4’.
1
1 • For Objective C: Like for C, and also ‘NSLocalizedString’,
1 ‘_’, ‘NSLocalizedStaticString’, ‘__’.
1
1 • For Shell scripts: ‘gettext’, ‘ngettext:1,2’, ‘eval_gettext’,
1 ‘eval_ngettext:1,2’.
1
1 • For Python: ‘gettext’, ‘ugettext’, ‘dgettext:2’,
1 ‘ngettext:1,2’, ‘ungettext:1,2’, ‘dngettext:2,3’, ‘_’.
1
1 • For Lisp: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
1
1 • For EmacsLisp: ‘_’.
1
1 • For librep: ‘_’.
1
1 • For Scheme: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
1
1 • For Java: ‘GettextResource.gettext:2’,
1 ‘GettextResource.ngettext:2,3’,
1 ‘GettextResource.pgettext:2c,3’,
1 ‘GettextResource.npgettext:2c,3,4’, ‘gettext’, ‘ngettext:1,2’,
1 ‘pgettext:1c,2’, ‘npgettext:1c,2,3’, ‘getString’.
1
1 • For C#: ‘GetString’, ‘GetPluralString:1,2’,
1 ‘GetParticularString:1c,2’,
1 ‘GetParticularPluralString:1c,2,3’.
1
1 • For awk: ‘dcgettext’, ‘dcngettext:1,2’.
1
1 • For Tcl: ‘::msgcat::mc’.
1
1 • For Perl: ‘gettext’, ‘%gettext’, ‘$gettext’, ‘dgettext:2’,
1 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
1 ‘dcngettext:2,3’, ‘gettext_noop’.
1
1 • For PHP: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
1 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dcngettext:2,3’.
1
1 • For Glade 1: ‘label’, ‘title’, ‘text’, ‘format’, ‘copyright’,
1 ‘comments’, ‘preview_text’, ‘tooltip’.
1
1 • For Lua: ‘_’, ‘gettext.gettext’, ‘gettext.dgettext:2’,
1 ‘gettext.dcgettext:2’, ‘gettext.ngettext:1,2’,
1 ‘gettext.dngettext:2,3’, ‘gettext.dcngettext:2,3’.
1
1 • For JavaScript: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
1 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘pgettext:1c,2’,
1 ‘dpgettext:2c,3’.
1
1 • For Vala: ‘_’, ‘Q_’, ‘N_’, ‘NC_’, ‘dgettext:2’, ‘dcgettext:2’,
1 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dpgettext:2c,3’,
1 ‘dpgettext2:2c,3’.
1
1 • For Desktop: ‘Name’, ‘GenericName’, ‘Comment’, ‘Icon’,
1 ‘Keywords’.
1
1 To disable the default keyword specifications, the option ‘-k’ or
1 ‘--keyword’ or ‘--keyword=’, without a KEYWORDSPEC, can be used.
1
1 ‘--flag=WORD:ARG:FLAG’
1 Specifies additional flags for strings occurring as part of the
1 ARGth argument of the function WORD. The possible flags are the
1 possible format string indicators, such as ‘c-format’, and their
1 negations, such as ‘no-c-format’, possibly prefixed with ‘pass-’.
1 The meaning of ‘--flag=FUNCTION:ARG:LANG-format’ is that in
1 language LANG, the specified FUNCTION expects as ARGth argument a
1 format string. (For those of you familiar with GCC function
1 attributes, ‘--flag=FUNCTION:ARG:c-format’ is roughly equivalent to
1 the declaration ‘__attribute__ ((__format__ (__printf__, ARG,
1 ...)))’ attached to FUNCTION in a C source file.) For example, if
1 you use the ‘error’ function from GNU libc, you can specify its
1 behaviour through ‘--flag=error:3:c-format’. The effect of this
1 specification is that ‘xgettext’ will mark as format strings all
1 ‘gettext’ invocations that occur as ARGth argument of FUNCTION.
1 This is useful when such strings contain no format string
1 directives: together with the checks done by ‘msgfmt -c’ it will
1 ensure that translators cannot accidentally use format string
1 directives that would lead to a crash at runtime.
1 The meaning of ‘--flag=FUNCTION:ARG:pass-LANG-format’ is that in
1 language LANG, if the FUNCTION call occurs in a position that must
1 yield a format string, then its ARGth argument must yield a format
1 string of the same type as well. (If you know GCC function
1 attributes, the ‘--flag=FUNCTION:ARG:pass-c-format’ option is
1 roughly equivalent to the declaration ‘__attribute__
1 ((__format_arg__ (ARG)))’ attached to FUNCTION in a C source file.)
1 For example, if you use the ‘_’ shortcut for the ‘gettext’
1 function, you should use ‘--flag=_:1:pass-c-format’. The effect of
1 this specification is that ‘xgettext’ will propagate a format
1 string requirement for a ‘_("string")’ call to its first argument,
1 the literal ‘"string"’, and thus mark it as a format string. This
1 is useful when such strings contain no format string directives:
1 together with the checks done by ‘msgfmt -c’ it will ensure that
1 translators cannot accidentally use format string directives that
1 would lead to a crash at runtime.
1 This option has an effect with most languages, namely C, C++,
1 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java,
1 C#, awk, YCP, Tcl, Perl, PHP, GCC-source, Lua, JavaScript, Vala.
1
1 ‘-T’
1 ‘--trigraphs’
1 Understand ANSI C trigraphs for input.
1 This option has an effect only with the languages C, C++,
1 ObjectiveC.
1
1 ‘--qt’
1 Recognize Qt format strings.
1 This option has an effect only with the language C++.
1
1 ‘--kde’
1 Recognize KDE 4 format strings.
1 This option has an effect only with the language C++.
1
1 ‘--boost’
1 Recognize Boost format strings.
1 This option has an effect only with the language C++.
1
1 ‘--debug’
1 Use the flags ‘c-format’ and ‘possible-c-format’ to show who was
1 responsible for marking a message as a format string. The latter
1 form is used if the ‘xgettext’ program decided, the former form is
1 used if the programmer prescribed it.
1
1 By default only the ‘c-format’ form is used. The translator should
1 not have to care about these details.
1
1 This implementation of ‘xgettext’ is able to process a few awkward
1 cases, like strings in preprocessor macros, ANSI concatenation of
1 adjacent strings, and escaped end of lines for continued strings.
1
1 5.1.7 Output details
1 --------------------
1
1 ‘--color’
1 ‘--color=WHEN’
1 Specify whether or when to use colors and other text attributes.
1 See ⇒The --color option for details.
1
1 ‘--style=STYLE_FILE’
11 Specify the CSS style rule file to use for ‘--color’. See ⇒
The --style option for details.
1
1 ‘--force-po’
1 Always write an output file even if no message is defined.
1
1 ‘-i’
1 ‘--indent’
1 Write the .po file using indented style.
1
1 ‘--no-location’
1 Do not write ‘#: FILENAME:LINE’ lines. Note that using this option
1 makes it harder for technically skilled translators to understand
1 each message’s context.
1
1 ‘-n’
1 ‘--add-location=TYPE’
1 Generate ‘#: FILENAME:LINE’ lines (default).
1
1 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
1 is not given or ‘full’, it generates the lines with both file name
1 and line number. If it is ‘file’, the line number part is omitted.
1 If it is ‘never’, it completely suppresses the lines (same as
1 ‘--no-location’).
1
1 ‘--strict’
1 Write out a strict Uniforum conforming PO file. Note that this
1 Uniforum format should be avoided because it doesn’t support the
1 GNU extensions.
1
1 ‘--properties-output’
1 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
1 that this file format doesn’t support plural forms and silently
1 drops obsolete messages.
1
1 ‘--stringtable-output’
1 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
1 syntax. Note that this file format doesn’t support plural forms.
1
1 ‘--its=FILE’
1 Use ITS rules defined in FILE. Note that this is only effective
1 with XML files.
1
1 ‘--itstool’
1 Write out comments recognized by itstool (<http://itstool.org>).
1 Note that this is only effective with XML files.
1
1 ‘-w NUMBER’
1 ‘--width=NUMBER’
1 Set the output page width. Long strings in the output files will
1 be split across multiple lines in order to ensure that each line’s
1 width (= number of screen columns) is less or equal to the given
1 NUMBER.
1
1 ‘--no-wrap’
1 Do not break long message lines. Message lines whose width exceeds
1 the output page width will not be split into several lines. Only
1 file reference lines which are wider than the output page width
1 will be split.
1
1 ‘-s’
1 ‘--sort-output’
1 Generate sorted output. Note that using this option makes it much
1 harder for the translator to understand each message’s context.
1
1 ‘-F’
1 ‘--sort-by-file’
1 Sort output by file location.
1
1 ‘--omit-header’
1 Don’t write header with ‘msgid ""’ entry.
1
1 This is useful for testing purposes because it eliminates a source
1 of variance for generated ‘.gmo’ files. With ‘--omit-header’, two
1 invocations of ‘xgettext’ on the same files with the same options
1 at different times are guaranteed to produce the same results.
1
1 Note that using this option will lead to an error if the resulting
1 file would not entirely be in ASCII.
1
1 ‘--copyright-holder=STRING’
1 Set the copyright holder in the output. STRING should be the
1 copyright holder of the surrounding package. (Note that the msgstr
1 strings, extracted from the package’s sources, belong to the
1 copyright holder of the package.) Translators are expected to
1 transfer or disclaim the copyright for their translations, so that
1 package maintainers can distribute them without legal risk. If
1 STRING is empty, the output files are marked as being in the public
1 domain; in this case, the translators are expected to disclaim
1 their copyright, again so that package maintainers can distribute
1 them without legal risk.
1
1 The default value for STRING is the Free Software Foundation, Inc.,
1 simply because ‘xgettext’ was first used in the GNU project.
1
1 ‘--foreign-user’
1 Omit FSF copyright in output. This option is equivalent to
1 ‘--copyright-holder=''’. It can be useful for packages outside the
1 GNU project that want their translations to be in the public
1 domain.
1
1 ‘--package-name=PACKAGE’
1 Set the package name in the header of the output.
1
1 ‘--package-version=VERSION’
1 Set the package version in the header of the output. This option
1 has an effect only if the ‘--package-name’ option is also used.
1
1 ‘--msgid-bugs-address=EMAIL@ADDRESS’
1 Set the reporting address for msgid bugs. This is the email
1 address or URL to which the translators shall report bugs in the
1 untranslated strings:
1
1 - Strings which are not entire sentences; see the maintainer
1 guidelines in ⇒Preparing Strings.
1 - Strings which use unclear terms or require additional context
1 to be understood.
1 - Strings which make invalid assumptions about notation of date,
1 time or money.
1 - Pluralisation problems.
1 - Incorrect English spelling.
1 - Incorrect formatting.
1
1 It can be your email address, or a mailing list address where
1 translators can write to without being subscribed, or the URL of a
1 web page through which the translators can contact you.
1
1 The default value is empty, which means that translators will be
1 clueless! Don’t forget to specify this option.
1
1 ‘-m[STRING]’
1 ‘--msgstr-prefix[=STRING]’
1 Use STRING (or "" if not specified) as prefix for msgstr values.
1
1 ‘-M[STRING]’
1 ‘--msgstr-suffix[=STRING]’
1 Use STRING (or "" if not specified) as suffix for msgstr values.
1
1 5.1.8 Informative output
1 ------------------------
1
1 ‘-h’
1 ‘--help’
1 Display this help and exit.
1
1 ‘-V’
1 ‘--version’
1 Output version information and exit.
1