<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52a
from gettext.texi on 6 August 2002 -->
<TITLE>GNU gettext utilities - 4 Making the PO Template File</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_3.html">previous</A>, <A HREF="gettext_5.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC20" HREF="gettext_toc.html#TOC20">4 Making the PO Template File</A></H1>
<P>
<A NAME="IDX149"></A>
</P>
<P>
After preparing the sources, the programmer creates a PO template file.
This section explains how to use <CODE>xgettext</CODE> for this purpose.
</P>
<P>
<CODE>xgettext</CODE> creates a file named <TT>`<VAR>domainname</VAR>.po´</TT>. You
should then rename it to <TT>`<VAR>domainname</VAR>.pot´</TT>. (Why doesn't
<CODE>xgettext</CODE> create it under the name <TT>`<VAR>domainname</VAR>.pot´</TT>
right away? The answer is: for historical reasons. When <CODE>xgettext</CODE>
was specified, the distinction between a PO file and PO file template
was fuzzy, and the suffix <SAMP>`.pot´</SAMP> wasn't in use at that time.)
</P>
<H2><A NAME="SEC21" HREF="gettext_toc.html#TOC21">4.1 Invoking the <CODE>xgettext</CODE> Program</A></H2>
<P>
<A NAME="IDX150"></A>
<A NAME="IDX151"></A>
<PRE>
xgettext [<VAR>option</VAR>] [<VAR>inputfile</VAR>] ...
</PRE>
<P>
The <CODE>xgettext</CODE> program extracts translatable strings from given
input files.
</P>
<H3><A NAME="SEC22" HREF="gettext_toc.html#TOC22">4.1.1 Input file location</A></H3>
<DL COMPACT>
<DT><SAMP>`<VAR>inputfile</VAR> ...´</SAMP>
<DD>
Input files.
<DT><SAMP>`-f <VAR>file</VAR>´</SAMP>
<DD>
<DT><SAMP>`--files-from=<VAR>file</VAR>´</SAMP>
<DD>
<A NAME="IDX152"></A>
<A NAME="IDX153"></A>
Read the names of the input files from <VAR>file</VAR> instead of getting
them from the command line.
<DT><SAMP>`-D <VAR>directory</VAR>´</SAMP>
<DD>
<DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP>
<DD>
<A NAME="IDX154"></A>
<A NAME="IDX155"></A>
Add <VAR>directory</VAR> to the list of directories. Source files are
searched relative to this list of directories. The resulting <TT>`.po´</TT>
file will be written relative to the current directory, though.
</DL>
<P>
If <VAR>inputfile</VAR> is <SAMP>`-´</SAMP>, standard input is read.
</P>
<H3><A NAME="SEC23" HREF="gettext_toc.html#TOC23">4.1.2 Output file location</A></H3>
<DL COMPACT>
<DT><SAMP>`-d <VAR>name</VAR>´</SAMP>
<DD>
<DT><SAMP>`--default-domain=<VAR>name</VAR>´</SAMP>
<DD>
<A NAME="IDX156"></A>
<A NAME="IDX157"></A>
Use <TT>`<VAR>name</VAR>.po´</TT> for output (instead of <TT>`messages.po´</TT>).
<DT><SAMP>`-o <VAR>file</VAR>´</SAMP>
<DD>
<DT><SAMP>`--output=<VAR>file</VAR>´</SAMP>
<DD>
<A NAME="IDX158"></A>
<A NAME="IDX159"></A>
Write output to specified file (instead of <TT>`<VAR>name</VAR>.po´</TT> or
<TT>`messages.po´</TT>).
<DT><SAMP>`-p <VAR>dir</VAR>´</SAMP>
<DD>
<DT><SAMP>`--output-dir=<VAR>dir</VAR>´</SAMP>
<DD>
<A NAME="IDX160"></A>
<A NAME="IDX161"></A>
Output files will be placed in directory <VAR>dir</VAR>.
</DL>
<P>
<A NAME="IDX162"></A>
If the output <VAR>file</VAR> is <SAMP>`-´</SAMP> or <SAMP>`/dev/stdout´</SAMP>, the output
is written to standard output.
</P>
<H3><A NAME="SEC24" HREF="gettext_toc.html#TOC24">4.1.3 Choice of input file language</A></H3>
<DL COMPACT>
<DT><SAMP>`-L <VAR>name</VAR>´</SAMP>
<DD>
<DT><SAMP>`--language=<VAR>name</VAR>´</SAMP>
<DD>
<A NAME="IDX163"></A>
<A NAME="IDX164"></A>
<A NAME="IDX165"></A>
Specifies the language of the input files. The supported languages
are <CODE>C</CODE>, <CODE>C++</CODE>, <CODE>ObjectiveC</CODE>, <CODE>PO</CODE>, <CODE>Python</CODE>,
<CODE>Lisp</CODE>, <CODE>EmacsLisp</CODE>, <CODE>librep</CODE>, <CODE>Java</CODE>, <CODE>awk</CODE>,
<CODE>YCP</CODE>, <CODE>Tcl</CODE>, <CODE>RST</CODE>, <CODE>Glade</CODE>.
<DT><SAMP>`-C´</SAMP>
<DD>
<DT><SAMP>`--c++´</SAMP>
<DD>
<A NAME="IDX166"></A>
<A NAME="IDX167"></A>
This is a shorthand for <CODE>--language=C++</CODE>.
</DL>
<P>
By default the language is guessed depending on the input file name
extension.
</P>
<H3><A NAME="SEC25" HREF="gettext_toc.html#TOC25">4.1.4 Operation mode</A></H3>
<DL COMPACT>
<DT><SAMP>`-j´</SAMP>
<DD>
<DT><SAMP>`--join-existing´</SAMP>
<DD>
<A NAME="IDX168"></A>
<A NAME="IDX169"></A>
Join messages with existing file.
<DT><SAMP>`-x <VAR>file</VAR>´</SAMP>
<DD>
<DT><SAMP>`--exclude-file=<VAR>file</VAR>´</SAMP>
<DD>
<A NAME="IDX170"></A>
<A NAME="IDX171"></A>
Entries from <VAR>file</VAR> are not extracted. <VAR>file</VAR> should be a PO or
POT file.
<DT><SAMP>`-c [<VAR>tag</VAR>]´</SAMP>
<DD>
<DT><SAMP>`--add-comments[=<VAR>tag</VAR>]´</SAMP>
<DD>
<A NAME="IDX172"></A>
<A NAME="IDX173"></A>
Place comment block with <VAR>tag</VAR> (or those preceding keyword lines)
in output file.
</DL>
<H3><A NAME="SEC26" HREF="gettext_toc.html#TOC26">4.1.5 Language=C/C++ specific options</A></H3>
<DL COMPACT>
<DT><SAMP>`-a´</SAMP>
<DD>
<DT><SAMP>`--extract-all´</SAMP>
<DD>
<A NAME="IDX174"></A>
<A NAME="IDX175"></A>
Extract all strings.
<DT><SAMP>`-k <VAR>keywordspec</VAR>´</SAMP>
<DD>
<DT><SAMP>`--keyword[=<VAR>keywordspec</VAR>]´</SAMP>
<DD>
<A NAME="IDX176"></A>
<A NAME="IDX177"></A>
Additional keyword to be looked for (without <VAR>keywordspec</VAR> means not to
use default keywords).
<A NAME="IDX178"></A>
If <VAR>keywordspec</VAR> is a C identifer <VAR>id</VAR>, <CODE>xgettext</CODE> looks
for strings in the first argument of each call to the function or macro
<VAR>id</VAR>. If <VAR>keywordspec</VAR> is of the form
<SAMP>`<VAR>id</VAR>:<VAR>argnum</VAR>´</SAMP>, <CODE>xgettext</CODE> looks for strings in the
<VAR>argnum</VAR>th argument of the call. If <VAR>keywordspec</VAR> is of the form
<SAMP>`<VAR>id</VAR>:<VAR>argnum1</VAR>,<VAR>argnum2</VAR>´</SAMP>, <CODE>xgettext</CODE> looks for
strings in the <VAR>argnum1</VAR>st argument and in the <VAR>argnum2</VAR>nd 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 <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
<CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
<CODE>dcngettext:2,3</CODE>, and <CODE>gettext_noop</CODE>.
<DT><SAMP>`-T´</SAMP>
<DD>
<DT><SAMP>`--trigraphs´</SAMP>
<DD>
<A NAME="IDX179"></A>
<A NAME="IDX180"></A>
<A NAME="IDX181"></A>
Understand ANSI C trigraphs for input.
<DT><SAMP>`--debug´</SAMP>
<DD>
<A NAME="IDX182"></A>
<A NAME="IDX183"></A>
Use the flags <KBD>c-format</KBD> and <KBD>possible-c-format</KBD> to show who was
responsible for marking a message as a format string. The latter form is
used if the <CODE>xgettext</CODE> program decided, the format form is used if
the programmer prescribed it.
By default only the <KBD>c-format</KBD> form is used. The translator should
not have to care about these details.
</DL>
<P>
This implementation of <CODE>xgettext</CODE> 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.
</P>
<H3><A NAME="SEC27" HREF="gettext_toc.html#TOC27">4.1.6 Output details</A></H3>
<DL COMPACT>
<DT><SAMP>`--force-po´</SAMP>
<DD>
<A NAME="IDX184"></A>
Always write an output file even if no message is defined.
<DT><SAMP>`-i´</SAMP>
<DD>
<DT><SAMP>`--indent´</SAMP>
<DD>
<A NAME="IDX185"></A>
<A NAME="IDX186"></A>
Write the .po file using indented style.
<DT><SAMP>`--no-location´</SAMP>
<DD>
<A NAME="IDX187"></A>
Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines.
<DT><SAMP>`-n´</SAMP>
<DD>
<DT><SAMP>`--add-location´</SAMP>
<DD>
<A NAME="IDX188"></A>
<A NAME="IDX189"></A>
Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default).
<DT><SAMP>`--strict´</SAMP>
<DD>
<A NAME="IDX190"></A>
Write out a strict Uniforum conforming PO file. Note that this
Uniforum format should be avoided because it doesn't support the
GNU extensions.
<DT><SAMP>`-w <VAR>number</VAR>´</SAMP>
<DD>
<DT><SAMP>`--width=<VAR>number</VAR>´</SAMP>
<DD>
<A NAME="IDX191"></A>
<A NAME="IDX192"></A>
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 <VAR>number</VAR>.
<DT><SAMP>`--no-wrap´</SAMP>
<DD>
<A NAME="IDX193"></A>
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.
<DT><SAMP>`-s´</SAMP>
<DD>
<DT><SAMP>`--sort-output´</SAMP>
<DD>
<A NAME="IDX194"></A>
<A NAME="IDX195"></A>
<A NAME="IDX196"></A>
Generate sorted output. Note that using this option makes it much harder
for the translator to understand each message's context.
<DT><SAMP>`-F´</SAMP>
<DD>
<DT><SAMP>`--sort-by-file´</SAMP>
<DD>
<A NAME="IDX197"></A>
<A NAME="IDX198"></A>
Sort output by file location.
<DT><SAMP>`--omit-header´</SAMP>
<DD>
<A NAME="IDX199"></A>
Don't write header with <SAMP>`msgid ""´</SAMP> entry.
<A NAME="IDX200"></A>
This is useful for testing purposes because it eliminates a source
of variance for generated <CODE>.gmo</CODE> files. With <CODE>--omit-header</CODE>,
two invocations of <CODE>xgettext</CODE> on the same files with the same
options at different times are guaranteed to produce the same results.
<DT><SAMP>`--copyright-holder=<VAR>string</VAR>´</SAMP>
<DD>
<A NAME="IDX201"></A>
Set the copyright holder in the output. <VAR>string</VAR> 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 <VAR>string</VAR> 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 <VAR>string</VAR> is the Free Software Foundation, Inc.,
simply because <CODE>xgettext</CODE> was first used in the GNU project.
<DT><SAMP>`--foreign-user´</SAMP>
<DD>
<A NAME="IDX202"></A>
Omit FSF copyright in output. This option is equivalent to
<SAMP>`--copyright-holder="´</SAMP>. It can be useful for packages outside the GNU
project that want their translations to be in the public domain.
<DT><SAMP>`-m [<VAR>string</VAR>]´</SAMP>
<DD>
<DT><SAMP>`--msgstr-prefix[=<VAR>string</VAR>]´</SAMP>
<DD>
<A NAME="IDX203"></A>
<A NAME="IDX204"></A>
Use <VAR>string</VAR> (or "" if not specified) as prefix for msgstr entries.
<DT><SAMP>`-M [<VAR>string</VAR>]´</SAMP>
<DD>
<DT><SAMP>`--msgstr-suffix[=<VAR>string</VAR>]´</SAMP>
<DD>
<A NAME="IDX205"></A>
<A NAME="IDX206"></A>
Use <VAR>string</VAR> (or "" if not specified) as suffix for msgstr entries.
</DL>
<H3><A NAME="SEC28" HREF="gettext_toc.html#TOC28">4.1.7 Informative output</A></H3>
<DL COMPACT>
<DT><SAMP>`-h´</SAMP>
<DD>
<DT><SAMP>`--help´</SAMP>
<DD>
<A NAME="IDX207"></A>
<A NAME="IDX208"></A>
Display this help and exit.
<DT><SAMP>`-V´</SAMP>
<DD>
<DT><SAMP>`--version´</SAMP>
<DD>
<A NAME="IDX209"></A>
<A NAME="IDX210"></A>
Output version information and exit.
</DL>
<P><HR><P>
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_3.html">previous</A>, <A HREF="gettext_5.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
</BODY>
</HTML>
