get_message_data {potools}

Extract user-visible messages from a package

Description

This function looks in the R and src directories of a package for user-visible messages and compiles them as a data.table::data.table() to facilitate analyzing this corpus as such.

Usage

get_message_data(
  dir = ".",
  custom_translation_functions = list(R = NULL, src = NULL),
  style = NULL,
  verbose = !is_testing()
)

Arguments

dir

Character, default the present directory; a directory in which an R package is stored.

custom_translation_functions

A list with either/both of two components, R and src, together governing how to extract any non-standard strings from the package.

See Details in translate_package().

style

Translation style, either "base" or "explict". The default, NULL, reads from the DESCRIPTION field Config/potools/style so you can specify the style once for your package.

Both styles extract strings explicitly flagged for translation with gettext() or ngettext(). The base style additionally extracts strings in calls to stop(), warning(), and message(), and to stopf(), warningf(), and messagef() if you have added those helpers to your package. The explicit style also accepts tr_() as a short hand for gettext(). See vignette("developer") for more details.

verbose

Logical, default TRUE (except during testing). Should extra information about progress, etc. be reported?

Value

A data.table with the following schema:

• message_source: character, either "R" or "src", saying whether the string was found in the R or the src folder of the package

• type: character, either "singular" or "plural"; "plural" means the string came from ngettext() and can be pluralized

• file: character, the file where the string was found

• msgid: character, the string (character literal or char array as found in the source); missing for all type == "plural" strings

• msgid_plural: list(character, character), the strings (character literals or char arrays as found in the source); the first applies in English for n=1 (see ngettext), while the second applies for n!=1; missing for all type == "singular" strings

• call: character, the full call containing the string that was found

• line_number: integer, the line in file where the string was found

• is_repeat: logical, whether the msgid is a duplicate within this message_source

• is_marked_for_translation:logical, whether the string is marked for translation (e.g., in R, all character literals supplied to a ... argument in stop() are so marked)

• is_templated, logical, whether the string is templatable (e.g., uses ⁠%s⁠ or other formatting markers)

Author(s)

Michael Chirico

See Also

translate_package(), write_po_file()

Examples

pkg <- system.file('pkg', package = 'potools')
get_message_data(pkg)

# includes strings provided to the custom R wrapper function catf()
get_message_data(pkg, custom_translation_functions = list(R = "catf:fmt|1"))

# includes untranslated strings provided to the custom
#   C/C++ wrapper function ReverseTemplateMessage()
get_message_data(
  pkg,
  custom_translation_functions = list(src = "ReverseTemplateMessage:2")
)

# cleanup
rm(pkg)