% File src/library/tools/man/xgettext.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2021 R Core Team
% Distributed under GPL 2 or later

\name{xgettext}
\title{Extract Translatable Messages from R Files in a Package}
\alias{xgettext}
\alias{xngettext}
\alias{xgettext2pot}
\description{
  For each file in the \file{R} directory (including system-specific
  subdirectories) of a \emph{source} package, extract the unique arguments passed
  to these \dQuote{message generating} calls;
  \describe{
    \item{for \code{xgettext()}:}{% see c("warning", "stop", ..) in ../R/xgettext.R :
      to \code{\link{stop}}, \code{\link{warning}}, \code{\link{message}},
      \code{\link{packageStartupMessage}}, \code{\link{gettext}} and
      \code{\link{gettextf}},}

    \item{for \code{xngettext()}:}{
      to \code{\link{ngettext}}.}
  }

  \code{xgettext2pot()} calls both \code{xgettext()} and then \code{xngettext()}.
}
\usage{
xgettext(dir, verbose = FALSE, asCall = TRUE)

xngettext(dir, verbose = FALSE)

xgettext2pot(dir, potFile, name = "R", version, bugs)
}
\arguments{
  \item{dir}{the directory of a source package, i.e., with a \file{./R} sub
    directory.}
  \item{verbose}{logical: should each file be listed as it is processed?}
  \item{asCall}{logical: if \code{TRUE} each argument is converted to
    string and returned whole, otherwise the string literals within each
    argument are extracted (recursively). See Examples.}

  \item{potFile}{name of \code{po} template file to be produced.
    Defaults to \file{R-\var{pkgname}.pot} where
    \var{pkgname} is the basename of \file{dir}.}
  \item{name, version, bugs}{as recorded in the template file:
    \code{version} defaults the version number of the currently running
    \R, and \code{bugs} to \code{"bugs.r-project.org"}.}
}
\details{
  Leading and trailing white space (space, tab and linefeed
  (aka newline, i.e., \code{\\n})) is removed
  for all the calls extracted by \code{xgettext()}, see
  \sQuote{Description} above,
  as it is by the internal code that passes strings for translation.

  We look to see if the matched functions were called with
  \code{domain = NA}.  If so, when \code{asCall} is true, the whole call
  is omitted.  Note that a call might contain a nested call
  to \code{gettext} (or \code{warning}, etc.) whose strings would be visible
  if \code{asCall} is false.

  \code{xgettext2pot} calls \code{xgettext} and then \code{xngettext},
  and writes a PO template file (to \code{potFile}) 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, but \command{msgfmt} complains if there is duplication between
  the sets.).

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

  For \code{xngettext}, a list of objects of class \code{"xngettext"},
  which are themselves lists of length-2 character vectors.
}
\seealso{
  \code{\link{update_pkg_po}()} which calls \code{xgettext2pot()}.
}
\examples{\dontrun{## in a source-directory build (not typical!) of R;
## otherwise, download and unpack the R sources, and replace
## R.home()  by  "<my_path_to_source_R>" :
xgettext(file.path(R.home(), "src", "library", "splines"))
}% dont..

## Create source package-like  <tmp>/R/foo.R  and get text from it:
tmpPkg <- tempdir()
tmpRDir <- file.path(tmpPkg, "R")
dir.create(tmpRDir, showWarnings = FALSE)
fnChar <- paste(sep = "\n",
  "foo <- function(x) {",
  "  if (x < -1)  stop('too small')",
  "  # messages unduplicated (not so for ngettext)",
  "  if (x < -.5) stop('too small')",
  "  if (x < 0) {",
  "    warning(",
  "      'sqrt(x) is', sqrt(as.complex(x)),",
  "      ', which may be too small'",
  "    )",
  "  }",
  "  # calls with domain=NA are skipped",
  "  if (x == 0) cat(gettext('x is 0!\n', domain=NA))",
  "  # gettext strings may be ignored due to 'outer' domain=NA",
  "  if (x > 10) stop('x is ', gettextf('\%.2f', x), domain=NA)",
  "  x",
  "}")

writeLines(fnChar, con = file.path(tmpRDir, "foo.R"))

## [[1]] : suppressing (tmpfile) name to make example Rdiff-able
xgettext(tmpPkg, asCall=TRUE )[[1]] # default; shows  ' sqrt(as.complex(x)) '
xgettext(tmpPkg, asCall=FALSE)[[1]] # doesn't ; but then ' \%.2f '

unlink(tmpRDir, recursive=TRUE)
}
\keyword{ utilities }