5.1.6 Language specific options

‘-a’

‘--extract-all’

Extract all strings.

This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala, GSettings.

‘-k[keywordspec]’

‘--keyword[=keywordspec]’

Specify keywordspec as an additional keyword to be looked for. Without a keywordspec, the option means to not use default keywords.

If keywordspec is a C identifier id, xgettext looks for strings in the first argument of each call to the function or macro id. If keywordspec is of the form ‘id:argnum’, xgettext looks for strings in the argnumth argument of the call. If keywordspec is of the form ‘id:argnum1,argnum2’, xgettext looks for strings in the argnum1st argument and in the argnum2nd argument of the call, and treats them as singular/plural variants for a message with plural handling. Also, if keywordspec is of the form ‘id:contextargnumc,argnum’ or ‘id:argnum,contextargnumc’, xgettext treats strings in the contextargnumth argument as a context specifier. And, as a special-purpose support for GNOME, if keywordspec is of the form ‘id:argnumg’, xgettext recognizes the argnumth argument as a string with context, using the GNOME glib syntax ‘"msgctxt|msgid"’.
Furthermore, if keywordspec is of the form ‘id:…,totalnumargst’, xgettext recognizes this argument specification only if the number of actual arguments is equal to totalnumargs. This is useful for disambiguating overloaded function calls in C++.
Finally, if keywordspec is of the form ‘id:argnum...,"xcomment"’, xgettext, when extracting a message from the specified argument strings, adds an extracted comment xcomment to the message. Note that when used through a normal shell command line, the double-quotes around the xcomment need to be escaped.

This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.

The default keyword specifications, which are always looked for if not explicitly disabled, are language dependent. They are:

• For C, C++, and GCC-source: gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3, gettext_noop, and pgettext:1c,2, dpgettext:2c,3, dcpgettext:2c,3, npgettext:1c,2,3, dnpgettext:2c,3,4, dcnpgettext:2c,3,4.
• For Objective C: Like for C, and also NSLocalizedString, _, NSLocalizedStaticString, __.
• For Shell scripts: gettext, ngettext:1,2, eval_gettext, eval_ngettext:1,2.
• For Python: gettext, ugettext, dgettext:2, ngettext:1,2, ungettext:1,2, dngettext:2,3, _.
• For Lisp: gettext, ngettext:1,2, gettext-noop.
• For EmacsLisp: _.
• For librep: _.
• For Scheme: gettext, ngettext:1,2, gettext-noop.
• For Java: GettextResource.gettext:2, GettextResource.ngettext:2,3, GettextResource.pgettext:2c,3, GettextResource.npgettext:2c,3,4, gettext, ngettext:1,2, pgettext:1c,2, npgettext:1c,2,3, getString.
• For C#: GetString, GetPluralString:1,2, GetParticularString:1c,2, GetParticularPluralString:1c,2,3.
• For awk: dcgettext, dcngettext:1,2.
• For Tcl: ::msgcat::mc.
• For Perl: gettext, %gettext, $gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3, gettext_noop.
• For PHP: _, gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3.
• For Glade 1: label, title, text, format, copyright, comments, preview_text, tooltip.
• For Lua: _, gettext.gettext, gettext.dgettext:2, gettext.dcgettext:2, gettext.ngettext:1,2, gettext.dngettext:2,3, gettext.dcngettext:2,3.
• For JavaScript: _, gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, pgettext:1c,2, dpgettext:2c,3.
• For Vala: _, Q_, N_, NC_, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dpgettext:2c,3, dpgettext2:2c,3.
• For Desktop: Name, GenericName, Comment, Icon, Keywords.

To disable the default keyword specifications, the option ‘-k’ or ‘--keyword’ or ‘--keyword=’, without a keywordspec, can be used.

‘--flag=word:arg:flag’

Specifies additional flags for strings occurring as part of the argth argument of the function word. The possible flags are the possible format string indicators, such as ‘c-format’, and their negations, such as ‘no-c-format’, possibly prefixed with ‘pass-’.
The meaning of --flag=function:arg:lang-format is that in language lang, the specified function expects as argth argument a format string. (For those of you familiar with GCC function attributes, --flag=function:arg:c-format is roughly equivalent to the declaration ‘__attribute__ ((__format__ (__printf__, arg, ...)))’ attached to function in a C source file.) For example, if you use the ‘error’ function from GNU libc, you can specify its behaviour through --flag=error:3:c-format. The effect of this specification is that xgettext will mark as format strings all gettext invocations that occur as argth argument of function. This is useful when such strings contain no format string directives: together with the checks done by ‘msgfmt -c’ it will ensure that translators cannot accidentally use format string directives that would lead to a crash at runtime.
The meaning of --flag=function:arg:pass-lang-format is that in language lang, if the function call occurs in a position that must yield a format string, then its argth argument must yield a format string of the same type as well. (If you know GCC function attributes, the --flag=function:arg:pass-c-format option is roughly equivalent to the declaration ‘__attribute__ ((__format_arg__ (arg)))’ attached to function in a C source file.) For example, if you use the ‘_’ shortcut for the gettext function, you should use --flag=_:1:pass-c-format. The effect of this specification is that xgettext will propagate a format string requirement for a _("string") call to its first argument, the literal "string", and thus mark it as a format string. This is useful when such strings contain no format string directives: together with the checks done by ‘msgfmt -c’ it will ensure that translators cannot accidentally use format string directives that would lead to a crash at runtime.
This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP, GCC-source, Lua, JavaScript, Vala.

‘-T’

‘--trigraphs’

Understand ANSI C trigraphs for input.
This option has an effect only with the languages C, C++, ObjectiveC.

‘--qt’

Recognize Qt format strings.
This option has an effect only with the language C++.

‘--kde’

Recognize KDE 4 format strings.
This option has an effect only with the language C++.

‘--boost’

Recognize Boost format strings.
This option has an effect only with the language C++.

‘--debug’

Use the flags c-format and possible-c-format to show who was responsible for marking a message as a format string. The latter form is used if the xgettext program decided, the format form is used if the programmer prescribed it.

By default only the c-format form is used. The translator should not have to care about these details.

This implementation of xgettext is able to process a few awkward cases, like strings in preprocessor macros, ANSI concatenation of adjacent strings, and escaped end of lines for continued strings.

This document was generated on June 7, 2014 using texi2html 5.0.