Translate messages in a different language than the one in the R session

Message translation in R is obtained with base::gettext() or base::ngettext(). But, there is no way to specify that one needs translated messages in a different language than the current one in R. Here are alternate functions that have an additional lang= argument allowing to do so. If the lang= argument is not provided in the call, they use the language defined in the R session. It is useful to define a different language, for instance, to keep R error and warning messages in English, but to generate translation for tables and figures in a different language in a report.

gettext_(..., domain = NULL, trim = TRUE, lang = get_sciviews_lang())

gettextf_(fmt, ..., domain = NULL, trim = TRUE, lang = get_sciviews_lang())

ngettext_(n, msg1, msg2, domain = NULL)

get_language(unset = "en")

set_language(lang, unset = get_language())

get_sciviews_lang(unset = get_language())

set_sciviews_lang(lang, unset = "en")

check_lang(lang, allow_uppercase = FALSE)

test_gettext_lang(lang = get_sciviews_lang(), n = 1)

Arguments

...: one of more character vectors.
domain: the 'domain' for the translation, a character string or NULL; see base::gettext() for more details. For ngettext_(), it should combine the domain and the lang, like "domain/lang" (e.g., "NULL/en_US" or "R-stats/fr"). This is a workaround to define the language, because base version of that function does not allow additional arguments and we have to remain compatible here.
trim: logical indicating if the white space trimming should happen.
lang: the target language (could be two lowercase letters, e.g., "en" for English, "fr" for French, "de" for German, etc.). One can also further specify variants, e.g., "en_US", or "en_GB", or even "fr_FR.UTF-8". For get_sciviews_lang() and set_sciviews_lang(), it is the secondary language. For the other functions, it is the R session language that is used by default. One can specify the alternate SciViews language globally with either the SCIVIEWS_LANG environment variable, or with the R option SciViews_lang, but it is a better practice to use set_sciviews_lang() in the R session. If missing, NULL, or "", the default is used from unset. For the SciViews language, uppercase letters are accepted, and they mean "translate more" (typically, factor and ordered levels are also translated, for instance).
fmt: a character vector of format strings, each of up to 8192 bytes.
n: a non-negative integer.
msg1: the message to be used in English for n = 1.
msg2: the message to be used in English for n = 0, 2, 3, ...
unset: The default language to use if not defined yet, "en" (English) by default for regular R language, and the currently defined R language for the alternate SciViews language.
allow_uppercase: logical indicating if uppercase letters are allowed for the first two letters of the language code (FALSE by default, but should be TRUE for the SciViews language).

Value

A character vector with translated messages for the gettext...() functions.

test_gettext_lang() just serves to test and demonstrate the translation in a given language.

get_language() and get_sciviews_lang() return the current language. set_language()and set_sciviews_lang() return the previous language invisibly (with an attribute attr(*, "ok") a logical indicating success.

check_lang() validates a lang= argument by returning TRUE invisibly, otherwise, it stop()s.

Details

To prepare your package for translation with these functions, you should import gettext_(), gettextf_() and ngettext_() from svBase. Then, you define gettext <- gettext_, gettextf <- gettextf_ and ngettext <- ngettext_ somewhere in your package. To prepare translation strings, you change the current directory of your R console to the base folder of the sources of your package and you issue tools::update_pkg_po(".") in R (or you include it in the tests: for an example, see tests/testthat/test-translations.R in the source of the svBase package). Then, you perform the translation for different languages with, say, poEdit, and recompile your package.

Examples

get_language()
#> [1] "en-US"
get_sciviews_lang()
#> [1] "en-US"

old_lang <- set_language("fr") # Switch to French for R language
old_sv_lang <- set_sciviews_lang("fr") # Switch to French for SciViews also

# R look for messages to be translated into gettext() calls, not gettext_()
# So, rename accordingly in your package:
gettext <- svBase::gettext_
gettextf <- svBase::gettextf_
ngettext <- svBase::ngettext_

# Retrieve strings in same language
gettext("empty model supplied", "incompatible dimensions",
 domain="R-stats", lang = "fr")
#> [1] "empty model supplied"    "incompatible dimensions"

# Retrieve strings in different languages
gettext("empty model supplied", "incompatible dimensions",
  domain="R-stats", lang = "en")
#> [1] "empty model supplied"    "incompatible dimensions"
gettext("empty model supplied", "incompatible dimensions",
  domain="R-stats", lang = "de")
#> [1] "empty model supplied"    "incompatible dimensions"

# Try to get strings translated in an unknown language (just return the strings)
gettext("empty model supplied", "incompatible dimensions",
  domain="R-stats", lang = "xx")
#> [1] "empty model supplied"    "incompatible dimensions"

# Test with some translations from the svMisc package itself:
svBase::test_gettext_lang()
#> [1] Test of svBase's `gettext()` and `gettextf()`:            
#> [2] This should be transtlated, if 'fr' language is supported.
#> [3] This is message number 3                                  
#> [4] You asked for only one item                               
svBase::test_gettext_lang("fr", n = 1)
#> [1] Test of svBase's `gettext()` and `gettextf()`:            
#> [2] This should be transtlated, if 'fr' language is supported.
#> [3] This is message number 3                                  
#> [4] You asked for only one item                               
svBase::test_gettext_lang("fr", n = 2)
#> [1] Test of svBase's `gettext()` and `gettextf()`:            
#> [2] This should be transtlated, if 'fr' language is supported.
#> [3] This is message number 3                                  
#> [4] You asked for several items                               
svBase::test_gettext_lang("en", n = 1)
#> [1] Test of svBase's `gettext()` and `gettextf()`:            
#> [2] This should be transtlated, if 'en' language is supported.
#> [3] This is message number 3                                  
#> [4] You asked for only one item                               
svBase::test_gettext_lang("en", n = 2)
#> [1] Test of svBase's `gettext()` and `gettextf()`:            
#> [2] This should be transtlated, if 'en' language is supported.
#> [3] This is message number 3                                  
#> [4] You asked for several items                               

# Restore original languages
set_language(old_lang)
set_sciviews_lang(old_sv_lang)
rm(old_lang, old_sv_lang, gettext, gettextf, ngettext)

# In case you must check if a lang= argument gets a correct value:
check_lang("en")
check_lang("en_US.UTF-8")
# Only for SciViews language!
check_lang("FR", allow_uppercase = TRUE)
# But these are incorrect
try(check_lang("EN"))
#> Error in check_lang("EN") : 
#>   Wrong `lang` argument (must be either 'C' or a language code).
#> ✖ It is `"EN"`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang(""))
#> Error in check_lang("") : 
#>   Wrong `lang` argument (must be either 'C' or a language code).
#> ✖ It is `""`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang(NA_character_))
#> Error in check_lang(NA_character_) : 
#>   Wrong `lang` argument (must be either 'C' or a language code).
#> ✖ It is `NA_character_`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang(NULL))
#> Error in check_lang(NULL) : 
#>   Argument `lang` is missing , or `NULL`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang(42))
#> Error in check_lang(42) : 
#>   The argument `lang` must be a single string.
#> ✖ It is `42`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang(c("en", "fr")))
#> Error in check_lang(c("en", "fr")) : 
#>   The argument `lang` must be a single string.
#> ✖ It is `c("en", "fr")`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)
try(check_lang("Fr", allow_uppercase = TRUE))
#> Error in check_lang("Fr", allow_uppercase = TRUE) : 
#>   Wrong `lang` argument (must be either 'C' or a language code).
#> ✖ It is `"Fr"`.
#> ℹ Provide a valid language code ('en', 'en_US.UTF-8', 'fr', 'de'...)

Translate messages in a different language than the one in the R session

Arguments

Value

Details

See also

Examples