In RL10N/poio: Input/Output Functionality for "PO" and "POT" Message Translation Files

poio: Input/Output Functionality for "PO" and "POT" Message Translation Files

R packages use a text file format with a .po extension to store translations of messages, warnings, and errors. poio provides functionality to read in these files, fix the metadata, and write the objects back to file.

Installation

To install the development version, you first need the devtools package.

install.packages("devtools")

Then you can install the poio package using

devtools::install_bitbucket("RL10N/poio")

Functions

read_po reads PO and POT files into R, and stores them as an object of class "po" (see below for details).

fix_metadata fixes the metadata in a po object.

generate_po_from_pot generates a PO object from a POT object.

write_po writes po objects back to a PO file.

get_n_plural_forms is a convenience function for retriving the number of plural forms for a language from the po object's metadata.

Datasets

language_codes is a list of all the language codes and the country codes that gettext understands.

plural_forms is a data.frame of the plural forms header string for over 140 common languages.

Examples

A typical workflow begins by generating a POT master translation file for a package using tools::xgettext2pot. In this case, we'll use a sample file stored in the poio package. The contents look like this:

library(poio)
pot_file <- system.file("extdata/R-summerof69.pot", package = "poio")
cat(readLines(pot_file), sep = "\n")

To import the file, use read_po. A description on the object's structure is shown in the "PO Objects" section below.

(pot <- read_po(pot_file))

tools::xgettext2pot makes a mess of some of the metadata element that it generates, so they need fixing. fix_metadata auto-guesses sensible options, but you can manually set values if you prefer.

pot_fixed <- fix_metadata(pot, "Language-Team" = "Team RL10N!")
pot_fixed$metadata

Now you need to choose some languages to translate your messages into. Suitable language codes can be found in the language_codes dataset included in the package.

data(language_codes)
str(language_codes, vec.len = 8)

Then, for each language that you want to create a translation for, generate a po object and write it to file. If your current working directory is the root of your package, the correct file name is automatically generated.

for(lang in c("de", "fr_BE"))
{
  po <- generate_po_from_pot(pot, lang)
  write_po(po)
}

PO Objects

po objects are lists with class "po" (to allow S3 methods), containing the following elements:

• source_type: A string. Either "r" or "c", depending upon whether the messages originated from R-level code, or C-level code.
• file_type: Either "po" or "pot", depending upon whether the messages originated from a PO (language-specific) or POT (master translation) file. Determined from the file name.
• initial_comments: A character vector of comments added by the translator.
• metadata: A data_frame of file metadata with columns "name" and "value".
• direct: A data_frame of messages with a direct translation, as created by stop, warning, message orgettext; its columns are described below.
• countable: A data_frameof messages where the translation depends upon a countable value, as created by ngettext; its columns are described below.

The direct element of the po object has the following columns.

• msgid: Character. The untranslated (should be American English) message.
• msgstr: Character. The translated message, or empty strings in the case of POT files.
• is_obsolete: Logical. Is the message obsolete?
• msgctxt: List of character. Disambiguating context information to allow multiple messages with the same ID.
• translator_comments: List of character. Comments added by the translator, typically to explain unclear messages, or why translation choices were made.
• source_reference_comments: List of character. Links to where the message occured in the source, in the form "filename:line".
• flags_comments: List of character. Typically used to describe formatting directives. R uses C-style formatting, which would imply a "c-format" flag. For example %d denotes an integer, and %s denotes a string. "fuzzy" flags can appear when PO files are merged.
• previous_string_comment: List of character. When PO files are merged with an updated POT file ,and a fuzzy flag is generated, the old msgid is stored in a previous string comment.

The countable element of the po object takes the same form as the direct element, with two differences.

• msgid_plural: Character. The plural form of the untranslated message.
• msgstr: This is now a list of character (rather than character.)

See Also

The msgtools package, which has higher level tools for working with messages and translations.

The Pology python library has some useful documentation on the PO file format.

The GNU gettext utility.

Acknowledgements

This package was developed as part of the RL10N project, funded by the R Consortium.

RL10N/poio documentation built on April 27, 2020, 3:50 a.m.