Merge pull request #546 from joelnitta/translate

WIP: Add Support for Translations
carpentries · Dec 7, 2023 · 600b562 · 600b562
2 parents e1a52fd + 1f51cf1
commit 600b562
Show file tree

Hide file tree

Showing 35 changed files with 2,164 additions and 29 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: sandpaper
 Title: Create and Curate Carpentries Lessons
-Version: 0.15.0
+Version: 0.15.0.9000
 Authors@R: c(
     person(given = "Zhian N.",
            family = "Kamvar",
@@ -44,6 +44,11 @@ Authors@R: c(
            role = c("ctb"),
            email = "milan.malfait94@gmail.com",
            comment = c(ORCID = "0000-0001-9144-3701")),
+    person(given = "Joel H.",
+           family = "Nitta",
+           role = c("aut", "trl"),
+           email = "joelnitta@gmail.com",
+           comment = c(ORCID = "0000-0003-4719-7472")),
     person())
 Description: We provide tools to build a Carpentries-themed lesson repository
   into an accessible standalone static website. These include local tools and
@@ -69,6 +74,7 @@ Imports:
     renv (>= 0.14.0),
     rprojroot,
     usethis (>= 2.0.0),
+    withr,
     whisker,
     callr,
     servr,
@@ -81,7 +87,6 @@ Suggests:
     brio,
     xml2,
     xslt,
-    withr,
     jsonlite,
     sessioninfo,
     mockr,
@@ -90,13 +95,14 @@ Additional_repositories: https://carpentries.r-universe.dev/
 Remotes:
   ropensci/tinkr,
   carpentries/pegboard,
-  carpentries/varnish
+  carpentries/varnish@add-l10n-support
 SystemRequirements: pandoc (>= 2.11.4) - https://pandoc.org
 Encoding: UTF-8
 LazyData: true
 Config/testthat/edition: 3
 Config/testthat/parallel: false
 Config/Needs/check: rstudio/renv
+Config/potools/style: explicit
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
 URL: https://carpentries.github.io/sandpaper/, https://github.com/carpentries/sandpaper/, https://carpentries.github.io/workbench/

diff --git a/NAMESPACE b/NAMESPACE
@@ -19,6 +19,7 @@ export(get_instructors)
 export(get_learners)
 export(get_profiles)
 export(get_syllabus)
+export(known_languages)
 export(manage_deps)
 export(move_episode)
 export(no_package_cache)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,34 @@
+# sandpaper 0.15.0.9000 (unreleased)
+
+## NEW FEATURES
+
+* It is now possible to build lessons in languages other than English so that
+  the website elements are also localised to that language (reported: @zkamvar,
+  #205, @joelnitta, #544; fixed: @joelnitta and @zkamvar, #546). 
+* `known_languages()` is a function that will return the language codes that are
+  known by {sandpaper}. 
+
+## DOCUMENTATION
+
+* A new vignette `vignette("translation", package = "sandpaper")` describes how
+  translation of template components works and how to submit new/update
+  translations.
+
+## BUG FIX
+
+* The spelling of keypoints is now consistent between the menu item and the
+  callout blocks (reported: @clarallebot, 
+  https://github.com/carpentries/workbench/issues/44; fixed: @zkamvar, #546)
+
+## DEPENDENCIES
+
+* The {withr} package has been upgraded to an import from a suggested package.
+
+## MISC
+
+* Added @joelnitta as an author and translator
+
+
 # sandpaper 0.15.0 (2023-11-29)
 
 ## NEW FEATURES

diff --git a/R/build_404.R b/R/build_404.R
@@ -54,7 +54,7 @@ build_404 <- function(pkg, quiet = FALSE) {
   this_dat <- list(
     this_page = "404.html",
     body = html,
-    pagetitle = "Page not found"
+    pagetitle = tr_("Page not found")
   )
   page_globals$instructor$update(this_dat)
   page_globals$learner$update(this_dat)

diff --git a/R/build_aio.R b/R/build_aio.R
@@ -3,7 +3,7 @@ build_aio <- function(pkg, pages = NULL, quiet = FALSE) {
   build_agg_page(
     pkg = pkg,
     pages = pages,
-    title = "All in One View",
+    title = tr_("All in One View"),
     slug = "aio",
     aggregate = "*",
     prefix = TRUE,

diff --git a/R/build_episode.R b/R/build_episode.R
@@ -131,7 +131,7 @@ get_nav_data <- function(path_md, path_src = NULL, home = NULL,
   pf_title <- NULL
 
   if (!is.null(page_back)) {
-    pb_title <- if (page_back == "index.md") "Home" else get_trimmed_title(page_back)
+    pb_title <- if (page_back == "index.md") tr_("Home") else get_trimmed_title(page_back)
     page_back <- as_html(page_back)
   }
   if (!is.null(page_forward)) {

diff --git a/R/build_home.R b/R/build_home.R
@@ -46,7 +46,7 @@ build_home <- function(pkg, quiet, next_page = NULL) {
   needs_title <- nav$pagetitle == ""
 
   if (needs_title) {
-    nav$pagetitle <- "Summary and Schedule"
+    nav$pagetitle <- tr_("Summary and Schedule")
   }
   nav$page_forward <- as_html(nav$page_forward, instructor = TRUE)
   page_globals$instructor$update(nav)
@@ -55,7 +55,7 @@ build_home <- function(pkg, quiet, next_page = NULL) {
   page_globals$instructor$set("setup", use_instructor(setup))
 
   if (needs_title) {
-    nav$pagetitle <- "Summary and Setup"
+    nav$pagetitle <- tr_("Summary and Setup")
   }
   nav$page_forward <- as_html(nav$page_forward)
   page_globals$learner$update(nav)
@@ -97,7 +97,7 @@ format_syllabus <- function(syl, use_col = TRUE) {
     )
   }
   td1 <- glue::glue(td_template, cls = "col-md-2", thing = syl$timings)
-  td2 <- glue::glue(td_template, cls = "col-md-3", thing = c(links, "Finish"))
+  td2 <- glue::glue(td_template, cls = "col-md-3", thing = c(links, tr_("Finish")))
   td3 <- glue::glue(td_template, cls = "col-md-7", thing = syl$questions)
   out <- glue::glue_collapse(glue::glue("<tr>{td1}{td2}{td3}</tr>"), sep = "\n")
   tmp <- tempfile(fileext = ".md")

diff --git a/R/build_html.R b/R/build_html.R
@@ -60,7 +60,9 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
   # Process instructor page ----------------------------------------------------
   update_sidebar(global_data$instructor, instructor_nodes, fs::path_file(this_page))
   meta$set("url", paste0(base_url, this_page))
+  translated <- fill_translation_vars(global_data$instructor$get())
   global_data$instructor$set("json", fill_metadata_template(meta))
+  global_data$instructor$set("translate", translated)
   modified <- pkgdown::render_page(pkg,
     template,
     data = global_data$instructor$get(),
@@ -71,6 +73,7 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
 
   # Process learner page if needed ---------------------------------------------
   if (modified) {
+    global_data$learner$set("translate", translated)
     this_page <- as_html(this_page)
     update_sidebar(global_data$learner, learner_nodes, fs::path_file(this_page))
     meta$set("url", paste0(base_url, this_page))

diff --git a/R/build_images.R b/R/build_images.R
@@ -3,7 +3,7 @@ build_images <- function(pkg, pages = NULL, quiet = FALSE) {
   build_agg_page(
     pkg = pkg,
     pages = pages,
-    title = "All Images",
+    title = tr_("All Images"),
     slug = "images",
     aggregate = "/img/..",
     prefix = FALSE,
@@ -46,7 +46,7 @@ make_images_section <- function(name, contents, parent) {
     content <- contents[[element]]
     alt <- xml2::xml_text(xml2::xml_find_all(content, "./img/@alt"))
     n <- length(alt)
-    xml2::xml_add_child(section, "h3", glue::glue("Figure {element}"),
+    xml2::xml_add_child(section, "h3", glue::glue(tr_("Figure {element}")),
       id = glue::glue("{name}-figure-{element}")
     )
     for (i in seq_along(alt)) {
@@ -57,7 +57,7 @@ make_images_section <- function(name, contents, parent) {
       if (txt == "") {
         txt <- "[decorative]"
       }
-      desc <- glue::glue("Image {i} of {n}: {sQuote(txt)}")
+      desc <- glue::glue(tr_("Image {i} of {n}: {sQuote(txt)}"))
       xml2::xml_add_child(section, "p", "aria-hidden" = "true", desc)
     }
     xml2::xml_add_child(section, contents[[element]])

diff --git a/R/build_instructor_notes.R b/R/build_instructor_notes.R
@@ -24,7 +24,7 @@ build_instructor_notes <- function(pkg, pages = NULL, built = NULL, quiet) {
     this_dat <- list(
       this_page = "instructor-notes.html",
       body = use_instructor(html),
-      pagetitle = "Instructor Notes"
+      pagetitle = tr_("Instructor Notes")
     )
 
     page_globals$instructor$update(this_dat)
@@ -135,7 +135,7 @@ make_instructor_note_linkback <- function(node, name) {
   title <- trimws(xml2::xml_text(node))
   id <- xml2::xml_attr(node, "id")
   newid <- glue::glue("{name}-{id}")
-  anchor <- glue::glue("<a class='anchor' aria-label='anchor' href='#{newid}'></a>")
+  anchor <- glue::glue("<a class='anchor' aria-label='{tr_('anchor')}' href='#{newid}'></a>")
   new <- "<h3><a href='{name}.html#{id}'>{title}</a>{anchor}</h3>"
   node <- xml2::read_xml(glue::glue(new))
   xml2::xml_set_attr(node, "id", newid)

diff --git a/R/build_keypoints.R b/R/build_keypoints.R
@@ -3,7 +3,7 @@ build_keypoints <- function(pkg, pages = NULL, quiet = FALSE) {
   build_agg_page(
     pkg = pkg,
     pages = pages,
-    title = "Key Points",
+    title = tr_("Key Points"),
     slug = "key-points",
     aggregate = "/div[starts-with(@id, 'keypoints')]/div[@class='callout-inner']/div[@class='callout-content']/*",
     prefix = FALSE,

diff --git a/R/build_profiles.R b/R/build_profiles.R
@@ -13,7 +13,7 @@ build_profiles <- function(pkg, quiet) {
   this_dat <- list(
     this_page = "profiles.html",
     body = use_instructor(html),
-    pagetitle = "Learner Profiles"
+    pagetitle = tr_("Learner Profiles")
   )
   page_globals$instructor$update(this_dat)
 

diff --git a/R/build_site.R b/R/build_site.R
@@ -31,6 +31,7 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   # Here we provision our website using pkgdown and either initialise it if it
   # does not exist or update the CSS, HTML, and JS if it does exist.
   pkg <- pkgdown::as_pkgdown(path_site(path), override = override)
+  set_language(this_metadata$get()[["lang"]])
   built_path <- fs::path(pkg$src_path, "built")
   # NOTE: This is a kludge to prevent pkgdown from displaying a bunch of noise
   #       if the user asks for quiet.

diff --git a/R/set_dropdown.R b/R/set_dropdown.R
@@ -100,6 +100,15 @@ set_dropdown <- function(path = ".", order = NULL, write = FALSE, folder) {
 #'
 #' The following keypairs are known by sandpaper, but are optional:
 #'
+#' - **lang** `[character]` the [language
+#'   code](https://www.gnu.org/software/gettext/manual/html_node/Usual-Language-Codes.html)
+#'   that matches the language of the lesson content. This defaults to `"en"`,
+#'   but can be any language code (e.g. "ja" specifying Japanese) or
+#'   combination language code and [country
+#'   code](https://www.gnu.org/software/gettext/manual/html_node/Country-Codes.html)
+#'   (e.g. "pt_BR" specifies Pourtugese used in Brazil). For more information
+#'   on how this is used, see [the Locale Names section of the gettext
+#'   manual](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html)
 #' - **url** `[character]` custom URL if you are deploying to a URL that is not
 #'   the default github pages io domain.
 #' - **fail_on_error** `[boolean]` for R Markdown lessons; fail the build if any

diff --git a/R/utils-cli.R b/R/utils-cli.R
@@ -41,6 +41,18 @@ warn_schedule <- function() {
   cli::cli_end(thm)
 }
 
+warn_no_language <- function(lang) {
+  thm <- cli::cli_div(theme = sandpaper_cli_theme())
+  wmsg <- "{.code {siQuote(lang)}} is not a language that has been defined in The Workbench."
+  cli::cli_alert_warning(wmsg)
+  amsg1 <- "Use {.code known_languages()} to see a list of known languages"
+  cli::cli_alert_info(cli::style_dim(amsg1), class = "alert-suggestion")
+  amsg2 <- c("To add a new language, consult {.code vignette('translations', package = 'sandpaper')}")
+  cli::cli_alert_info(cli::style_dim(amsg2), class = "alert-suggestion")
+
+  cli::cli_end(thm)
+}
+
 show_changed_yaml <- function(sched, order, yaml, what = "episodes") {
 
   # display for the user to distinguish what was added and what was taken

diff --git a/R/utils-potools.R b/R/utils-potools.R
@@ -0,0 +1,3 @@
+tr_ <- function(...) {
+  enc2utf8(gettext(paste0(...), domain = "R-sandpaper"))
+}