Go to the first, previous, next, last
section, table of contents.
After preparing the sources, the programmer creates a PO
template file. This section explains how to use
xgettext
for this purpose.
xgettext
creates a file named
`domainname.po´. You should then rename it
to `domainname.pot´. (Why doesn't
xgettext
create it under the name
`domainname.pot´ right away? The answer
is: for historical reasons. When xgettext
was
specified, the distinction between a PO file and PO file template
was fuzzy, and the suffix `.pot´ wasn't in use at
that time.)
xgettext [option] [inputfile] ...
The xgettext
program extracts translatable strings
from given input files.
- `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.
- `-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.
- `-L name´
- `--language=name´
- Specifies the
language of the input files. The supported languages are
C
, C++
, ObjectiveC
,
PO
, Python
, Lisp
,
EmacsLisp
, librep
,
Smalltalk
, Java
,
JavaProperties
, awk
, YCP
,
Tcl
, PHP
, RST
,
Glade
.
- `-C´
- `--c++´
- This is a shorthand for
--language=C++
.
By default the language is guessed depending on the input file
name extension.
- `--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 Python, 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.
- `-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.
- `-a´
- `--extract-all´
- Extract all strings.
- `-k keywordspec´
- `--keyword[=keywordspec]´
- Additional keyword to be looked for (without
keywordspec means not to use default keywords). If keywordspec is a C
identifer 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. The default keyword specifications, which are always
looked for if not explicitly disabled, are gettext
,
dgettext:2
, dcgettext:2
,
ngettext:1,2
, dngettext:2,3
,
dcngettext:2,3
, and gettext_noop
.
- `-T´
- `--trigraphs´
- Understand
ANSI C trigraphs for input.
- `--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.
- `--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.
- `-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 section 3.2 Preparing
Translatable 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.
- `-h´
- `--help´
- Display this help and exit.
- `-V´
- `--version´
- Output version information and exit.
Go to the first, previous, next, last
section, table of contents.