R: Extract Translatable Messages from R Files in a Package

xgettext {tools} | R Documentation

## Extract Translatable Messages from R Files in a Package

### Description

For each file in the ‘R’ directory (including system-specific subdirectories) of a package, extract the unique arguments passed to `stop`, `warning`, `message`, `gettext` and `gettextf`, or to `ngettext`.

### Usage

    xgettext(dir, verbose = FALSE, asCall = TRUE)

    xngettext(dir, verbose = FALSE)

    xgettext2pot(dir, potFile, name = "R", version, bugs)

### Arguments

`dir` | the directory of a source package.
`verbose` | logical: should each file be listed as it is processed?
`asCall` | logical: if `TRUE` each argument is returned whole, otherwise the strings within each argument are extracted.
`potFile` | name of `po` template file to be produced. Defaults to ‘R-pkgname.pot’ where pkgname is the basename of ‘dir’.
`name, version, bugs` | as recorded in the template file: `version` defaults the version number of the currently running R, and `bugs` to `"bugs.r-project.org"`.

### Details

Leading and trailing white space (space, tab and linefeed) is removed for calls to `gettext`, `gettextf`, `stop`, `warning`, and `message`, as it is by the internal code that passes strings for translation.

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

`xgettext2pot` calls `xgettext` and then `xngettext`, and writes a PO template file for use with the GNU Gettext tools. This ensures that the strings for simple translation are unique in the file (as GNU Gettext requires), but does not do so for `ngettext` calls (and the rules are not stated in the Gettext manual, but `msgfmt` complains if there is duplication between the sets.).

If applied to the base package, this also looks in the ‘.R’ files in ‘R_HOME/share/R’.

### Value

For `xgettext`, a list of objects of class `"xgettext"` (which has a `print` method), one per source file that potentially contains translatable strings.

For `xngettext`, a list of objects of class `"xngettext"`, which are themselves lists of length-2 character strings.

### See Also

`update_pkg_po()` which calls `xgettext2pot()`.

### Examples

    ## Not run: ## in a source-directory build of R:
    xgettext(file.path(R.home(), "src", "library", "splines"))

    ## End(Not run)

[Package tools version 3.1.2 Index]