| % File src/library/tools/man/xgettext.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2014 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 package, extract the unique arguments passed |
| to \code{\link{stop}}, \code{\link{warning}}, \code{\link{message}}, |
| \code{\link{gettext}} and \code{\link{gettextf}}, or to |
| \code{\link{ngettext}}. |
| } |
| \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.} |
| \item{verbose}{logical: should each file be listed as it is processed?} |
| \item{asCall}{logical: if \code{TRUE} each argument is returned whole, |
| otherwise the strings within each argument are extracted.} |
| |
| \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) 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, 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 |
| potentially contains translatable strings. |
| |
| For \code{xngettext}, a list of objects of class \code{"xngettext"}, |
| which are themselves lists of length-2 character strings. |
| } |
| \seealso{ |
| \code{\link{update_pkg_po}()} which calls \code{xgettext2pot()}. |
| } |
| \examples{\dontrun{## in a source-directory build of R: |
| xgettext(file.path(R.home(), "src", "library", "splines")) |
| }} |
| \keyword{ utilities } |