DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gettext.info.gz) xgettext Invocation

Info Catalog (gettext.info.gz) Template (gettext.info.gz) Template
 
 5.1 Invoking the `xgettext' Program
 ===================================
 
      xgettext [OPTION] [INPUTFILE] ...
 
    The `xgettext' program extracts translatable strings from given
 input files.
 
 5.1.1 Input file location
 -------------------------
 
 `INPUTFILE ...'
      Input files.
 
 `-f FILE'
 `--files-from=FILE'
      Read the names of the input files from FILE instead of getting
      them from the command line.
 
 `-D DIRECTORY'
 `--directory=DIRECTORY'
      Add DIRECTORY to the list of directories.  Source files are
      searched relative to this list of directories.  The resulting `.po'
      file will be written relative to the current directory, though.
 
 
    If INPUTFILE is `-', standard input is read.
 
 5.1.2 Output file location
 --------------------------
 
 `-d NAME'
 `--default-domain=NAME'
      Use `NAME.po' for output (instead of `messages.po').
 
 `-o FILE'
 `--output=FILE'
      Write output to specified file (instead of `NAME.po' or
      `messages.po').
 
 `-p DIR'
 `--output-dir=DIR'
      Output files will be placed in directory DIR.
 
 
    If the output FILE is `-' or `/dev/stdout', the output is written to
 standard output.
 
 5.1.3 Choice of input file language
 -----------------------------------
 
 `-L NAME'
 `--language=NAME'
      Specifies the language of the input files.  The supported languages
      are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp',
      `librep', `Scheme', `Smalltalk', `Java', `JavaProperties', `C#',
      `awk', `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable',
      `RST', `Glade'.
 
 `-C'
 `--c++'
      This is a shorthand for `--language=C++'.
 
 
    By default the language is guessed depending on the input file name
 extension.
 
 5.1.4 Input file interpretation
 -------------------------------
 
 `--from-code=NAME'
      Specifies the encoding of the input files.  This option is needed
      only if some untranslated message strings or their corresponding
      comments contain non-ASCII characters.  Note that Tcl and Glade
      input files are always assumed to be in UTF-8, regardless of this
      option.
 
 
    By default the input files are assumed to be in ASCII.
 
 5.1.5 Operation mode
 --------------------
 
 `-j'
 `--join-existing'
      Join messages with existing file.
 
 `-x FILE'
 `--exclude-file=FILE'
      Entries from FILE are not extracted.  FILE should be a PO or POT
      file.
 
 `-c [TAG]'
 `--add-comments[=TAG]'
      Place comment block with TAG (or those preceding keyword lines) in
      output file.
 
 
 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.
 
 `-k KEYWORDSPEC'
 `--keyword[=KEYWORDSPEC]'
      Additional keyword to be looked for (without KEYWORDSPEC means not
      to 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.
 
      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', `gettext', `ngettext:1,2',
           `getString'.
 
         * For C#: `GetString', `GetPluralString:1,2'.
 
         * 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'.
 
      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.
 
 `-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++.
 
 `--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.
 
 5.1.7 Output details
 --------------------
 
 `--force-po'
      Always write an output file even if no message is defined.
 
 `-i'
 `--indent'
      Write the .po file using indented style.
 
 `--no-location'
      Do not write `#: FILENAME:LINE' lines.
 
 `-n'
 `--add-location'
      Generate `#: FILENAME:LINE' lines (default).
 
 `--strict'
      Write out a strict Uniforum conforming PO file.  Note that this
      Uniforum format should be avoided because it doesn't support the
      GNU extensions.
 
 `--properties-output'
      Write out a Java ResourceBundle in Java `.properties' syntax.  Note
      that this file format doesn't support plural forms and silently
      drops obsolete messages.
 
 `--stringtable-output'
      Write out a NeXTstep/GNUstep localized resource file in `.strings'
      syntax.  Note that this file format doesn't support plural forms.
 
 `-w NUMBER'
 `--width=NUMBER'
      Set the output page width.  Long strings in the output files will
      be split across multiple lines in order to ensure that each line's
      width (= number of screen columns) is less or equal to the given
      NUMBER.
 
 `--no-wrap'
      Do not break long message lines.  Message lines whose width
      exceeds the output page width will not be split into several
      lines.  Only file reference lines which are wider than the output
      page width will be split.
 
 `-s'
 `--sort-output'
      Generate sorted output.  Note that using this option makes it much
      harder for the translator to understand each message's context.
 
 `-F'
 `--sort-by-file'
      Sort output by file location.
 
 `--omit-header'
      Don't write header with `msgid ""' entry.
 
      This is useful for testing purposes because it eliminates a source
      of variance for generated `.gmo' files.  With `--omit-header', two
      invocations of `xgettext' on the same files with the same options
      at different times are guaranteed to produce the same results.
 
 `--copyright-holder=STRING'
      Set the copyright holder in the output.  STRING should be the
      copyright holder of the surrounding package.  (Note that the msgstr
      strings, extracted from the package's sources, belong to the
      copyright holder of the package.)  Translators are expected to
      transfer or disclaim the copyright for their translations, so that
      package maintainers can distribute them without legal risk.  If
      STRING is empty, the output files are marked as being in the
      public domain; in this case, the translators are expected to
      disclaim their copyright, again so that package maintainers can
      distribute them without legal risk.
 
      The default value for STRING is the Free Software Foundation, Inc.,
      simply because `xgettext' was first used in the GNU project.
 
 `--foreign-user'
      Omit FSF copyright in output.  This option is equivalent to
      `--copyright-holder='''.  It can be useful for packages outside
      the GNU project that want their translations to be in the public
      domain.
 
 `--msgid-bugs-address=EMAIL@ADDRESS'
      Set the reporting address for msgid bugs.  This is the email
      address or URL to which the translators shall report bugs in the
      untranslated strings:
 
         - Strings which are not entire sentences, see the maintainer
           guidelines in  Preparing Strings.
 
         - Strings which use unclear terms or require additional context
           to be understood.
 
         - Strings which make invalid assumptions about notation of
           date, time or money.
 
         - Pluralisation problems.
 
         - Incorrect English spelling.
 
         - Incorrect formatting.
 
      It can be your email address, or a mailing list address where
      translators can write to without being subscribed, or the URL of a
      web page through which the translators can contact you.
 
      The default value is empty, which means that translators will be
      clueless!  Don't forget to specify this option.
 
 `-m [STRING]'
 `--msgstr-prefix[=STRING]'
      Use STRING (or "" if not specified) as prefix for msgstr entries.
 
 `-M [STRING]'
 `--msgstr-suffix[=STRING]'
      Use STRING (or "" if not specified) as suffix for msgstr entries.
 
 
 5.1.8 Informative output
 ------------------------
 
 `-h'
 `--help'
      Display this help and exit.
 
 `-V'
 `--version'
      Output version information and exit.
 
 
Info Catalog (gettext.info.gz) Template (gettext.info.gz) Template
automatically generated byinfo2html