\HeaderA{xgettext}{Extract Translatable Messages from R Files in a Package}{xgettext}
\aliasA{xgettext2pot}{xgettext}{xgettext2pot}
\aliasA{xngettext}{xgettext}{xngettext}
\keyword{utilities}{xgettext}
\begin{Description}\relax
For each file in the \file{R} directory (including system-specific
subdirectories) of a package, extract the unique arguments passed
to \code{\LinkA{stop}{stop}}, \code{\LinkA{warning}{warning}}, \code{\LinkA{message}{message}},
\code{\LinkA{gettext}{gettext}} and \code{\LinkA{gettextf}{gettextf}}, or to
\code{\LinkA{ngettext}{ngettext}}.
\end{Description}
\begin{Usage}
\begin{verbatim}
xgettext(dir, verbose = FALSE, asCall = TRUE)

xngettext(dir, verbose = FALSE)

xgettext2pot(dir, potFile)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{dir}] the directory of a source package.
\item[\code{verbose}] logical: should each file be listed as it is processed?
\item[\code{asCall}] logical: if \code{TRUE} each argument is returned whole,
otherwise the strings within each argument are extracted.
\item[\code{potFile}] name of \code{po} template file to be produced.
Defaults to \code{"R-\var{pkgname}.pot"} where
\var{pkgname} is the basename of \code{dir}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Leading and trailing white space (space, tab and linefeed) is removed
for calls to \code{gettext}, \code{gettextf}, \code{stop},
\code{warning}, and \code{message}, as it is by the internal code that
passes strings for translation.

We look to see if these functions were called with \code{domain = NA}
and if so omit the call if \code{asCall = TRUE}: note that the
call might contain a call to \code{gettext} which would be visible if
\code{asCall = FALSE}.

\code{xgettext2pot} calls \code{xgettext} and then \code{xngettext},
and writes a PO template file for use with the \pkg{GNU Gettext}
tools.  This ensures that the strings for simple translation are
unique in the file (as \pkg{GNU Gettext} requires), but does not do so
for \code{ngettext} calls (and the rules are not stated in the Gettext
manual).

If applied to the \pkg{base} package, this also looks in the \file{.R}
files in \file{\var{\LinkA{R\_HOME}{R.Rul.HOME}}/share/R}.
\end{Details}
\begin{Value}
For \code{xgettext}, a list of objects of class \code{"xgettext"}
(which has a \code{print} method), one per source file that
potentially contains translatable strings.

For \code{xngettext}, a list of objects of class \code{"xngettext"},
which are themselves lists of length-2 character strings.
\end{Value}
\begin{Examples}
\begin{ExampleCode}## Not run: 
## in a source-directory build of R:
xgettext(file.path(R.home(), "src", "library", "splines"))
## End(Not run)\end{ExampleCode}
\end{Examples}

