| [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
After preparing the sources, the programmer creates a PO template file.
jpayne@68: This section explains how to use xgettext for this purpose.
jpayne@68:
xgettext creates a file named ‘domainname.po’. You
jpayne@68: should then rename it to ‘domainname.pot’. (Why doesn't
jpayne@68: xgettext create it under the name ‘domainname.pot’
jpayne@68: right away? The answer is: for historical reasons. When xgettext
jpayne@68: was specified, the distinction between a PO file and PO file template
jpayne@68: was fuzzy, and the suffix ‘.pot’ wasn't in use at that time.)
jpayne@68:
xgettext Program xgettext [option] [inputfile] … jpayne@68: |
The xgettext program extracts translatable strings from given
jpayne@68: input files.
jpayne@68:
Input files. jpayne@68:
jpayne@68:Read the names of the input files from file instead of getting jpayne@68: them from the command line. jpayne@68:
jpayne@68:Add directory to the list of directories. Source files are jpayne@68: searched relative to this list of directories. The resulting ‘.po’ jpayne@68: file will be written relative to the current directory, though. jpayne@68:
jpayne@68:If inputfile is ‘-’, standard input is read. jpayne@68:
jpayne@68: jpayne@68: jpayne@68:Use ‘name.po’ for output (instead of ‘messages.po’). jpayne@68:
jpayne@68:Write output to specified file (instead of ‘name.po’ or jpayne@68: ‘messages.po’). jpayne@68:
jpayne@68:Output files will be placed in directory dir. jpayne@68:
jpayne@68:If the output file is ‘-’ or ‘/dev/stdout’, the output jpayne@68: is written to standard output. jpayne@68:
jpayne@68: jpayne@68: jpayne@68:Specifies the language of the input files. The supported languages
jpayne@68: are C, C++, ObjectiveC, PO, Shell,
jpayne@68: Python, Lisp, EmacsLisp, librep, Scheme,
jpayne@68: Smalltalk, Java, JavaProperties, C#, awk,
jpayne@68: YCP, Tcl, Perl, PHP, Ruby,
jpayne@68: GCC-source, NXStringTable, RST, RSJ, Glade,
jpayne@68: Lua, JavaScript, Vala, GSettings, Desktop.
jpayne@68:
This is a shorthand for --language=C++.
jpayne@68:
By default the language is guessed depending on the input file name jpayne@68: extension. jpayne@68:
jpayne@68: jpayne@68: jpayne@68:Specifies the encoding of the input files. This option is needed only jpayne@68: if some untranslated message strings or their corresponding comments jpayne@68: contain non-ASCII characters. Note that Tcl and Glade input files are jpayne@68: always assumed to be in UTF-8, regardless of this option. jpayne@68:
jpayne@68:By default the input files are assumed to be in ASCII. jpayne@68:
jpayne@68: jpayne@68: jpayne@68:Join messages with existing file. jpayne@68:
jpayne@68:Entries from file are not extracted. file should be a PO or jpayne@68: POT file. jpayne@68:
jpayne@68:Place comment blocks starting with tag and preceding keyword lines jpayne@68: in the output file. Without a tag, the option means to put all jpayne@68: comment blocks preceding keyword lines in the output file. jpayne@68:
jpayne@68:Note that comment blocks are only extracted if there is no program code jpayne@68: between the comment and the string that gets extracted. jpayne@68: For example, in the following C source code: jpayne@68:
jpayne@68:/* This is the first comment. */
jpayne@68: gettext ("foo");
jpayne@68:
jpayne@68: /* This is the second comment: not extracted */
jpayne@68: gettext (
jpayne@68: "bar");
jpayne@68:
jpayne@68: gettext (
jpayne@68: /* This is the third comment. */
jpayne@68: "baz");
jpayne@68:
jpayne@68: /* This is the fourth comment. */
jpayne@68:
jpayne@68: gettext ("I love blank lines in my programs");
jpayne@68: |
the second comment line will not be extracted, because there is a line jpayne@68: with some tokens between the comment line and the line that contains jpayne@68: the string. But the fourth comment is extracted, because between it and jpayne@68: the line with the string there is merely a blank line. jpayne@68:
jpayne@68:Perform a syntax check on msgid and msgid_plural. The supported checks jpayne@68: are: jpayne@68:
jpayne@68:Prefer Unicode ellipsis character over ASCII ...
jpayne@68:
Prohibit whitespace before an ellipsis character jpayne@68:
jpayne@68:Prefer Unicode quotation marks over ASCII "'`
jpayne@68:
Prefer Unicode bullet character over ASCII * or -
jpayne@68:
The option has an effect on all input files. To enable or disable
jpayne@68: checks for a certain string, you can mark it with an xgettext:
jpayne@68: special comment in the source file. For example, if you specify the
jpayne@68: --check=space-ellipsis option, but want to suppress the check on
jpayne@68: a particular string, add the following comment:
jpayne@68:
/* xgettext: no-space-ellipsis-check */
jpayne@68: gettext ("We really want a space before ellipsis here ...");
jpayne@68: |
The xgettext: comment can be followed by flags separated with a
jpayne@68: comma. The possible flags are of the form ‘[no-]name-check’,
jpayne@68: where name is the name of a valid syntax check. If a flag is
jpayne@68: prefixed by no-, the meaning is negated.
jpayne@68:
Some tests apply the checks to each sentence within the msgid, rather
jpayne@68: than the whole string. xgettext detects the end of sentence by
jpayne@68: performing a pattern match, which usually looks for a period followed by
jpayne@68: a certain number of spaces. The number is specified with the
jpayne@68: --sentence-end option.
jpayne@68:
The supported values are: jpayne@68:
jpayne@68:Expect at least one whitespace after a period jpayne@68:
jpayne@68:Expect at least two whitespaces after a period jpayne@68:
jpayne@68:Extract all strings. jpayne@68:
jpayne@68:This option has an effect with most languages, namely C, C++, ObjectiveC, jpayne@68: Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, jpayne@68: GCC-source, Glade, Lua, JavaScript, Vala, GSettings. jpayne@68:
jpayne@68:Specify keywordspec as an additional keyword to be looked for. jpayne@68: Without a keywordspec, the option means to not use default keywords. jpayne@68:
jpayne@68: jpayne@68: jpayne@68:If keywordspec is a C identifier id, xgettext looks
jpayne@68: for strings in the first argument of each call to the function or macro
jpayne@68: id. If keywordspec is of the form
jpayne@68: ‘id:argnum’, xgettext looks for strings in the
jpayne@68: argnumth argument of the call. If keywordspec is of the form
jpayne@68: ‘id:argnum1,argnum2’, xgettext looks for
jpayne@68: strings in the argnum1st argument and in the argnum2nd argument
jpayne@68: of the call, and treats them as singular/plural variants for a message
jpayne@68: with plural handling. Also, if keywordspec is of the form
jpayne@68: ‘id:contextargnumc,argnum’ or
jpayne@68: ‘id:argnum,contextargnumc’, xgettext treats
jpayne@68: strings in the contextargnumth argument as a context specifier.
jpayne@68: And, as a special-purpose support for GNOME, if keywordspec is of the
jpayne@68: form ‘id:argnumg’, xgettext recognizes the
jpayne@68: argnumth argument as a string with context, using the GNOME glib
jpayne@68: syntax ‘"msgctxt|msgid"’.
jpayne@68:
jpayne@68: Furthermore, if keywordspec is of the form
jpayne@68: ‘id:…,totalnumargst’, xgettext recognizes this
jpayne@68: argument specification only if the number of actual arguments is equal to
jpayne@68: totalnumargs. This is useful for disambiguating overloaded function
jpayne@68: calls in C++.
jpayne@68:
jpayne@68: Finally, if keywordspec is of the form
jpayne@68: ‘id:argnum...,"xcomment"’, xgettext, when
jpayne@68: extracting a message from the specified argument strings, adds an extracted
jpayne@68: comment xcomment to the message. Note that when used through a normal
jpayne@68: shell command line, the double-quotes around the xcomment need to be
jpayne@68: escaped.
jpayne@68:
This option has an effect with most languages, namely C, C++, ObjectiveC, jpayne@68: Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, jpayne@68: GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop. jpayne@68:
jpayne@68:The default keyword specifications, which are always looked for if not jpayne@68: explicitly disabled, are language dependent. They are: jpayne@68:
jpayne@68:gettext, dgettext:2,
jpayne@68: dcgettext:2, ngettext:1,2, dngettext:2,3,
jpayne@68: dcngettext:2,3, gettext_noop, and pgettext:1c,2,
jpayne@68: dpgettext:2c,3, dcpgettext:2c,3, npgettext:1c,2,3,
jpayne@68: dnpgettext:2c,3,4, dcnpgettext:2c,3,4.
jpayne@68:
jpayne@68: NSLocalizedString, _,
jpayne@68: NSLocalizedStaticString, __.
jpayne@68:
jpayne@68: gettext, ngettext:1,2, eval_gettext,
jpayne@68: eval_ngettext:1,2, eval_pgettext:1c,2,
jpayne@68: eval_npgettext:1c,2,3.
jpayne@68:
jpayne@68: gettext, ugettext, dgettext:2,
jpayne@68: ngettext:1,2, ungettext:1,2, dngettext:2,3, _.
jpayne@68:
jpayne@68: gettext, ngettext:1,2, gettext-noop.
jpayne@68:
jpayne@68: _.
jpayne@68:
jpayne@68: _.
jpayne@68:
jpayne@68: gettext, ngettext:1,2, gettext-noop.
jpayne@68:
jpayne@68: GettextResource.gettext:2,
jpayne@68: GettextResource.ngettext:2,3, GettextResource.pgettext:2c,3,
jpayne@68: GettextResource.npgettext:2c,3,4, gettext, ngettext:1,2,
jpayne@68: pgettext:1c,2, npgettext:1c,2,3, getString.
jpayne@68:
jpayne@68: GetString, GetPluralString:1,2,
jpayne@68: GetParticularString:1c,2, GetParticularPluralString:1c,2,3.
jpayne@68:
jpayne@68: dcgettext, dcngettext:1,2.
jpayne@68:
jpayne@68: ::msgcat::mc.
jpayne@68:
jpayne@68: gettext, %gettext, $gettext, dgettext:2,
jpayne@68: dcgettext:2, ngettext:1,2, dngettext:2,3,
jpayne@68: dcngettext:2,3, gettext_noop.
jpayne@68:
jpayne@68: _, gettext, dgettext:2, dcgettext:2,
jpayne@68: ngettext:1,2, dngettext:2,3, dcngettext:2,3.
jpayne@68:
jpayne@68: label, title, text, format,
jpayne@68: copyright, comments, preview_text, tooltip.
jpayne@68:
jpayne@68: _, gettext.gettext, gettext.dgettext:2,
jpayne@68: gettext.dcgettext:2, gettext.ngettext:1,2,
jpayne@68: gettext.dngettext:2,3, gettext.dcngettext:2,3.
jpayne@68:
jpayne@68: _, gettext, dgettext:2,
jpayne@68: dcgettext:2, ngettext:1,2, dngettext:2,3,
jpayne@68: pgettext:1c,2, dpgettext:2c,3.
jpayne@68:
jpayne@68: _, Q_, N_, NC_, dgettext:2,
jpayne@68: dcgettext:2, ngettext:1,2, dngettext:2,3,
jpayne@68: dpgettext:2c,3, dpgettext2:2c,3.
jpayne@68:
jpayne@68: Name, GenericName, Comment,
jpayne@68: Keywords.
jpayne@68: To disable the default keyword specifications, the option ‘-k’ or jpayne@68: ‘--keyword’ or ‘--keyword=’, without a keywordspec, can be jpayne@68: used. jpayne@68:
jpayne@68:Specifies additional flags for strings occurring as part of the argth
jpayne@68: argument of the function word. The possible flags are the possible
jpayne@68: format string indicators, such as ‘c-format’, and their negations,
jpayne@68: such as ‘no-c-format’, possibly prefixed with ‘pass-’.
jpayne@68:
jpayne@68:
jpayne@68: The meaning of --flag=function:arg:lang-format
jpayne@68: is that in language lang, the specified function expects as
jpayne@68: argth argument a format string. (For those of you familiar with
jpayne@68: GCC function attributes, --flag=function:arg:c-format is
jpayne@68: roughly equivalent to the declaration
jpayne@68: ‘__attribute__ ((__format__ (__printf__, arg, ...)))’ attached
jpayne@68: to function in a C source file.)
jpayne@68: For example, if you use the ‘error’ function from GNU libc, you can
jpayne@68: specify its behaviour through --flag=error:3:c-format. The effect of
jpayne@68: this specification is that xgettext will mark as format strings all
jpayne@68: gettext invocations that occur as argth argument of
jpayne@68: function.
jpayne@68: This is useful when such strings contain no format string directives:
jpayne@68: together with the checks done by ‘msgfmt -c’ it will ensure that
jpayne@68: translators cannot accidentally use format string directives that would
jpayne@68: lead to a crash at runtime.
jpayne@68:
jpayne@68:
jpayne@68: The meaning of --flag=function:arg:pass-lang-format
jpayne@68: is that in language lang, if the function call occurs in a
jpayne@68: position that must yield a format string, then its argth argument
jpayne@68: must yield a format string of the same type as well. (If you know GCC
jpayne@68: function attributes, the --flag=function:arg:pass-c-format
jpayne@68: option is roughly equivalent to the declaration
jpayne@68: ‘__attribute__ ((__format_arg__ (arg)))’ attached to function
jpayne@68: in a C source file.)
jpayne@68: For example, if you use the ‘_’ shortcut for the gettext function,
jpayne@68: you should use --flag=_:1:pass-c-format. The effect of this
jpayne@68: specification is that xgettext will propagate a format string
jpayne@68: requirement for a _("string") call to its first argument, the literal
jpayne@68: "string", and thus mark it as a format string.
jpayne@68: This is useful when such strings contain no format string directives:
jpayne@68: together with the checks done by ‘msgfmt -c’ it will ensure that
jpayne@68: translators cannot accidentally use format string directives that would
jpayne@68: lead to a crash at runtime.
jpayne@68:
jpayne@68: This option has an effect with most languages, namely C, C++, ObjectiveC,
jpayne@68: Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
jpayne@68: GCC-source, Lua, JavaScript, Vala.
jpayne@68:
Understand ANSI C trigraphs for input.
jpayne@68:
jpayne@68: This option has an effect only with the languages C, C++, ObjectiveC.
jpayne@68:
Recognize Qt format strings.
jpayne@68:
jpayne@68: This option has an effect only with the language C++.
jpayne@68:
Recognize KDE 4 format strings.
jpayne@68:
jpayne@68: This option has an effect only with the language C++.
jpayne@68:
Recognize Boost format strings.
jpayne@68:
jpayne@68: This option has an effect only with the language C++.
jpayne@68:
Use the flags c-format and possible-c-format to show who was
jpayne@68: responsible for marking a message as a format string. The latter form is
jpayne@68: used if the xgettext program decided, the former form is used if
jpayne@68: the programmer prescribed it.
jpayne@68:
By default only the c-format form is used. The translator should
jpayne@68: not have to care about these details.
jpayne@68:
This implementation of xgettext is able to process a few awkward
jpayne@68: cases, like strings in preprocessor macros, ANSI concatenation of
jpayne@68: adjacent strings, and escaped end of lines for continued strings.
jpayne@68:
Specify whether or when to use colors and other text attributes.
jpayne@68: See The --color option for details.
jpayne@68:
Specify the CSS style rule file to use for --color.
jpayne@68: See The --style option for details.
jpayne@68:
Always write an output file even if no message is defined. jpayne@68:
jpayne@68:Write the .po file using indented style. jpayne@68:
jpayne@68:Do not write ‘#: filename:line’ lines. Note that using jpayne@68: this option makes it harder for technically skilled translators to understand jpayne@68: each message's context. jpayne@68:
jpayne@68:Generate ‘#: filename:line’ lines (default). jpayne@68:
jpayne@68:The optional type can be either ‘full’, ‘file’, or
jpayne@68: ‘never’. If it is not given or ‘full’, it generates the
jpayne@68: lines with both file name and line number. If it is ‘file’, the
jpayne@68: line number part is omitted. If it is ‘never’, it completely
jpayne@68: suppresses the lines (same as --no-location).
jpayne@68:
Write out a strict Uniforum conforming PO file. Note that this jpayne@68: Uniforum format should be avoided because it doesn't support the jpayne@68: GNU extensions. jpayne@68:
jpayne@68:Write out a Java ResourceBundle in Java .properties syntax. Note
jpayne@68: that this file format doesn't support plural forms and silently drops
jpayne@68: obsolete messages.
jpayne@68:
Write out a NeXTstep/GNUstep localized resource file in .strings syntax.
jpayne@68: Note that this file format doesn't support plural forms.
jpayne@68:
Use ITS rules defined in file. jpayne@68: Note that this is only effective with XML files. jpayne@68:
jpayne@68:Write out comments recognized by itstool (http://itstool.org). jpayne@68: Note that this is only effective with XML files. jpayne@68:
jpayne@68:Set the output page width. Long strings in the output files will be jpayne@68: split across multiple lines in order to ensure that each line's width jpayne@68: (= number of screen columns) is less or equal to the given number. jpayne@68:
jpayne@68:Do not break long message lines. Message lines whose width exceeds the jpayne@68: output page width will not be split into several lines. Only file reference jpayne@68: lines which are wider than the output page width will be split. jpayne@68:
jpayne@68:Generate sorted output (deprecated). Note that using this option makes it jpayne@68: much harder for the translator to understand each message's context. jpayne@68:
jpayne@68:Sort output by file location. jpayne@68:
jpayne@68:Don't write header with ‘msgid ""’ entry. jpayne@68:
jpayne@68: jpayne@68:This is useful for testing purposes because it eliminates a source
jpayne@68: of variance for generated .gmo files. With --omit-header,
jpayne@68: two invocations of xgettext on the same files with the same
jpayne@68: options at different times are guaranteed to produce the same results.
jpayne@68:
Note that using this option will lead to an error if the resulting file jpayne@68: would not entirely be in ASCII. jpayne@68:
jpayne@68:Set the copyright holder in the output. string should be the jpayne@68: copyright holder of the surrounding package. (Note that the msgstr jpayne@68: strings, extracted from the package's sources, belong to the copyright jpayne@68: holder of the package.) Translators are expected to transfer or disclaim jpayne@68: the copyright for their translations, so that package maintainers can jpayne@68: distribute them without legal risk. If string is empty, the output jpayne@68: files are marked as being in the public domain; in this case, the translators jpayne@68: are expected to disclaim their copyright, again so that package maintainers jpayne@68: can distribute them without legal risk. jpayne@68:
jpayne@68:The default value for string is the Free Software Foundation, Inc.,
jpayne@68: simply because xgettext was first used in the GNU project.
jpayne@68:
Omit FSF copyright in output. This option is equivalent to jpayne@68: ‘--copyright-holder=''’. It can be useful for packages outside the GNU jpayne@68: project that want their translations to be in the public domain. jpayne@68:
jpayne@68:Set the package name in the header of the output. jpayne@68:
jpayne@68:Set the package version in the header of the output. This option has an jpayne@68: effect only if the ‘--package-name’ option is also used. jpayne@68:
jpayne@68:Set the reporting address for msgid bugs. This is the email address or URL jpayne@68: to which the translators shall report bugs in the untranslated strings: jpayne@68:
jpayne@68:It can be your email address, or a mailing list address where translators jpayne@68: can write to without being subscribed, or the URL of a web page through jpayne@68: which the translators can contact you. jpayne@68:
jpayne@68:The default value is empty, which means that translators will be clueless! jpayne@68: Don't forget to specify this option. jpayne@68:
jpayne@68:Use string (or "" if not specified) as prefix for msgstr values. jpayne@68:
jpayne@68:Use string (or "" if not specified) as suffix for msgstr values. jpayne@68:
jpayne@68:Display this help and exit. jpayne@68:
jpayne@68:Output version information and exit. jpayne@68:
jpayne@68:Increase verbosity level. jpayne@68:
jpayne@68:| [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
jpayne@68:
jpayne@68: This document was generated by Bruno Haible on February, 21 2024 using texi2html 1.78a.
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: