Internationalization

In learnr: Interactive Tutorials for R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

## Language codes and names borrowed from BootBox
# library(rvest)
# read_html("https://bootboxjs.com/v5.x/documentation.html") %>%
#   html_table() %>%
#   .[[6]] %>%
#   {dplyr::bind_rows(.[, 1:2], .[, 3:4])}

languages <- c("Arabic","Bulgarian","Czech",
    "German","English","Estonian","Farsi / Persian",
    "French / Français","Croatian","Indonesian","Japanese",
    "Korean","Latvian","Norwegian","Portuguese","Slovak",
    "Albanian","Swahili","Thai","Ukrainian",
    "Chinese (People's Republic of China)","Azerbaijani",
    "Portuguese - Brazil","Danish","Greek","Spanish / Español","Basque",
    "Finnish","Hebrew","Hungarian","Italian","Georgian",
    "Lithuanian","Dutch","Polish","Russian","Slovenian",
    "Swedish","Tamil","Turkish","Vietnamese",
    "Chinese (Taiwan / Republic of China)")

names(languages) <- c("ar","bg_BG","cs","de","en",
  "et","fa","fr","hr","id","ja","ko","lv","no",
  "pt","sk","sq","sw","th","uk","zh_CN","az","br",
  "da","el","es","eu","fi","he","hu","it","ka","lt",
  "nl","pl","ru","sl","sv","ta","tr","vi","zh_TW")


i18n_custom_language_defaults <- function(parent_key, docs = TRUE) {
  default <- learnr:::i18n_translations()$en$translation
  parent_key <- match.arg(parent_key, names(default))
  x <- default[[parent_key]]
  if (!isTRUE(docs)) return(x)
  paste0(
    parent_key, ":\n",
    paste0("  ", names(x), ": ", unname(unlist(x)), collapse = "\n"),
    sep = ""
  )
}

learnr_langs <- setdiff(names(learnr:::i18n_translations()), "emo")
learnr_supported_languages <- knitr::combine_words(paste0('`"', learnr_langs, '"`'))
bb_langs_code <- paste0("`", names(languages), "`")

Choosing a Tutorial's Language

To change the language of the UI element, you can use the following parameter in your YAML:

output:
  learnr::tutorial:
    language: fr

Currently, r length(learnr_langs) language translations are supported:

for (lng in learnr_langs) {
  lng_name <- if (lng %in% names(languages)) paste(" for", languages[lng])
  if (lng == "en") paste(lng_name, "(default)")
  cat("\n- `", lng, "`", lng_name, sep = "")
}

Customizable UI elements:

There are many elements whose language can be translated or customized, each identified by a key. Note that you do not need to customize all of the keys, the UI will fall back to the default tutorial language for keys that are not specifically customized.

The keys are organized into 2 groups: button and text.

Buttons

The following keys are available for translating button text:

`r i18n_custom_language_defaults("button")`

Text

The following keys are available for translating text elements:

`r i18n_custom_language_defaults("text")`

Format of language Option in YAML Header:

There are several ways that you can use the language option to choose a language translation or to customize the phrasing used in a particular language.

Default Language

Chose the default language for the tutorial. learnr currently provides complete translations for r learnr_supported_languages. A translation does not need to be available for you to use as the default language, in particular if you are providing a custom translation for a language without an available complete translation.

If you only want to change the default language, use:

language: "fr"

If you are also providing language customizations, the first language in the list of customizations will be the default language.

Customizing a Single Language

To customize the displayed text for a single language, use the following format. In this format the customization will be applied to the English translation, which will also be the default language of the tutorial.

language:
  en:
    button:
      runcode: Run!
    text:
      startover: Restart!

Customizing Multiple Languages

To provide custom display text for multiple languages, provide a list containing button and/or text custom labels. In the example below, the default tutorial language will be Spanish (es).

language:
  es:
    button:
      runcode: Ejecutar
  en:
    button:
      runcode: Run!
    text:
      startover: Restart!

Note that only the first language and its customizations are used in the rendered tutorial. In the future, we may extend the multi-language features of learnr to accommodate dynamic localization.

Store Customizations in a JSON File

If you intend to reuse the same custom language repeatedly, it may be helpful to store the custom language parameters in a JSON file and simply import the file. In this case, you can set the language code item to the path to a single JSON file, written with the same structure as the YAML.

For example, you could write Spanish language customizations to tutorial_es.json with the following R code:

jsonlite::write_json(
  list(
    button = list(runcode = "Ejecutar"),
    text = list(startover = "Empezar de nuevo")
  ),
  path = "tutorial_es.json",
  auto_unbox = TRUE
)

You could then load customizations from this file by referencing it in the YAML header.

language:
  es: tutorial_es.json

Similarly, you can store the entire language list in a JSON file and provide the path to the JSON file to the language key.

jsonlite::write_json(
  list(
    en = list(
      button = list(runcode = "Run the code"),
      text = list(startover = "Restart the tutorial")
    ),
    es = list(
      button = list(runcode = "Ejecutar"),
      text = list(startover = "Empezar de nuevo")
    )
  ),
  path = "custom_language.json",
  auto_unbox = TRUE
)

The R code above writes the custom text for en and es languages into custom_language.json, which we then reference in the YAML header:

language: custom_language.json

Complete Translations

Complete translations are provided by the internal function i18n_translations(). To contribute a complete translation for a language not currently provided by learnr, please submit a pull request to github.com/rstudio/learnr updating the list in data-raw/i18n_translations.yml, following the format described in that file.

Note that for the language to be available inside the alert boxes of learnr, you'll need to set the language to one of the language codes used by bootbox[^1]. If your language is not available for bootbox, then the buttons will default to English.

[^1]: r knitr::combine_words(bb_langs_code, and = " or ")

learnr documentation built on Sept. 28, 2023, 9:06 a.m.