Learn R Programming

potools: Tools for Portability and Internationalization of R packages

Overview

R users are a global community. From Xiamen to Santiago, Addis Ababa to Tbilisi, Ogallala to Adelaide, R users are legion and speak many different languages. To serve these diverse communities, R includes built-in tools based on the GNU gettext system that make it possible to translate user-facing communications like messages, warnings, and errors. Unfortunately, this system uses new file types (.pot templates, .po files, and .mo binaries) that come with their own quirks and idiosyncrasies. The goal of potools is make it as easy as possible to translate your package by abstracting away as many details of the gettext system as possible.

The potool logo features a potoo and was designed by Allison Horst.

Installation

Start by installing the released version potools from CRAN:

install.packages("potools")

Or the development version from GitHub:

# install.packages("remotes")
remotes::install_github("MichaelChirico/potools")

You'll also need to install gettext, the GNU command line toolkit that powers potools. Installation depends on your operating system:

  • On Windows, gettext is bundled with Rtools, so if you're developing packages you probably already have it.

  • On Mac, it's easiest to install with brew: brew install gettext

  • On Linux, it's usually already installed; otherwise you'll need to install gettext with your distro's standard tool.

Workflow

There are two core workflows provided by potools:

  • translate_package() is a one-stop-shop for interactively setting your package and providing translations, as described in ?translate_package.

  • po_extract(), po_create(), po_update(), and po_compile() let you perform the individual steps of translate_package() as described in vignette("developers") and vignette("translators").

Alternative software

potools is by no means the first tool for facilitating internationalization; other open-source projects have deeper experience in this domain and as a result there are some relatively mature options for working with gettext/the po ecosystem in general. Here is a smattering of such tools that I've come across:

Copy Link

Version

Install

install.packages('potools')

Monthly Downloads

1,500

Version

0.2.4

License

GPL-3

Issues

Pull Requests

Stars

Forks

Maintainer

Last Published

October 30th, 2023

Functions in potools (0.2.4)

write_po_file

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

Check for cracked messages in C/C++ sources
translate_package

Interactively provide translations for a package's messages
potools-package

potools: Tools for Internationalization and Portability in R Packages
check_untranslated_cat

Check for untranslated messages emitted by cat
po_create

Create a new .po file
po_explain_plurals

Explain plural message criteria verbally
po_extract

Extract messages for translation into a .pot file
get_message_data

Extract user-visible messages from a package
po_compile

Compile .po files to .mo
po_update

Update all .po files with changes in .pot
check_potools_sys_reqs

Check if the proper system utilities for running package translation are installed
check_cracked_messages

Check for cracked messages more suitable for templating