write_po_file {potools}

Write a .po or .pot file corresponding to a message database

Description

Serialize a message database in the ‘.po’ and ‘.pot’ formats recognized by the gettext ecosystem.

Usage

write_po_file(
  message_data,
  po_file,
  metadata,
  width = 79L,
  wrap_at_newline = TRUE,
  use_base_rules = metadata$package %chin% .potools$base_package_names
)

po_metadata(
  package = "",
  version = "",
  language = "",
  author = "",
  email = "",
  bugs = "",
  copyright = NULL,
  ...
)

## S3 method for class 'po_metadata'
format(x, template = FALSE, use_plurals = FALSE, ...)

## S3 method for class 'po_metadata'
print(x, ...)

Arguments

message_data

data.table, as returned from get_message_data(). NB: R creates separate domains for R and C/C++ code; it is recommended you do the same by filtering the get_message_data output for message_source == "R" or message_source == "src". Other approaches are untested.

po_file

Character vector giving a destination path. Paths ending in ‘.pot’ will be written with template files (e.g., msgstr entries will be blanked).

metadata

A po_metadata object as returned by po_metadata().

width

Numeric governing the wrapping width of the output file. Default is 79L to match the behavior of the xgettext utility. Inf turns off wrapping (except for file source markers comments).

wrap_at_newline

Logical, default TRUE to match the xgettext utility's behavior. If TRUE, any msgid or msgstr will always be wrapped at an internal newline (i.e., literally matching ⁠\n⁠).

use_base_rules

Logical; Should internal behavior match base behavior as strictly as possible? TRUE if being run on a base package (i.e., base or one of the default packages like utils, graphics, etc.). See Details.

package

Character; the name of the package being translated.

version

Character; the version of the package being translated.

language

Character; the language of the msgstr. See translate_package() for details.

author

Character; an author (combined with email) to whom to attribute the translations (as Last-Translator).

email

Character; an e-mail address associated with author.

bugs

Character; a URL where issues with the translations can be reported.

copyright

An object used to construct the initial Copyright reference in the output. If NULL, no such comment is written. If a list, it should the following structure:

• year: Required, A year or hyphen-separated range of years

• holder: Required, The name of the copyright holder

• title: Optional, A title for the ‘.po’

• additional: Optional, A character vector of additional lines for the copyright comment section

If a character scalar, it is interpreted as the holder and the year is set as the POT-Creation-Date's year.

...

Additional (named) components to add to the metadata. For print.po_metadata, passed on to format.po_metadata

x

A po_metadata object.

template

Logical; format the metadata as in a ‘.pot’ template?

use_plurals

Logical; should the Plural-Forms entry be included?

Details

Three components are set automatically if not provided:

• pot_timestamp - A POSIXct used to write the POT-Creation-Date entry. Defaults to the Sys.time() at run time.

• po_timestamp - A POSIXct used to write the PO-Revision-Date entry. Defaults to be the same as pot_timestamp.

• language_team - A string used to write the Language-Team entry. Defaults to be the same as language; if provided manually, the format ⁠LANGUAGE <[e-mail]>⁠ is recommended.

The charset for output is always set to "UTF-8"; this is intentional to make it more cumbersome to create non-UTF-8 files.

Value

For po_metadata, an object of class po_metadata that has a format method used to serialize the metadata.

Author(s)

Michael Chirico

References

https://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html

See Also

translate_package(), get_message_data(), tools::xgettext2pot(), tools::update_pkg_po()

Examples

message_data <- get_message_data(system.file('pkg', package='potools'))
desc_data <- read.dcf(system.file('pkg', 'DESCRIPTION', package='potools'), c('Package', 'Version'))
metadata <- po_metadata(
  package = desc_data[, "Package"], version = desc_data[, "Version"],
  language = 'ar_SY', author = 'R User', email = '[e-mail]',
  bugs = 'https://github.com/ruser/potoolsExample/issues'
)

# add fake translations
message_data[type == "singular", msgstr := "<arabic translation>"]
# Arabic has 6 plural forms
message_data[type == "plural", msgstr_plural := .(as.list(sprintf("<%d translation>", 0:5)))]

# Preview metadata
print(metadata)
# write .po file
write_po_file(
  message_data[message_source == "R"],
  tmp_po <- tempfile(fileext = '.po'),
  metadata
)
writeLines(readLines(tmp_po))

# write .pot template
write_po_file(
  message_data[message_source == "R"],
  tmp_pot <- tempfile(fileext = '.pot'),
  metadata
)
writeLines(readLines(tmp_pot))

# cleanup
file.remove(tmp_po, tmp_pot)
rm(message_data, desc_data, metadata, tmp_po, tmp_pot)