[pull] l2d from carpentries:main

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: sandpaper
 Title: Create and Curate Carpentries Lessons
-Version: 0.15.0.9000
+Version: 0.16.0
 Authors@R: c(
     person(given = "Zhian N.",
            family = "Kamvar",
@@ -97,7 +97,6 @@ Suggests:
     varnish (>= 0.3.0)
 Additional_repositories: https://carpentries.r-universe.dev/
 Remotes:
-  ropensci/tinkr,
   carpentries/pegboard,
   carpentries/varnish
 SystemRequirements: pandoc (>= 2.11.4) - https://pandoc.org

NEWS.md

@@ -1,4 +1,4 @@
-# sandpaper 0.15.0.9000 (unreleased)
+# sandpaper 0.16.0 (2023-12-13)
 
 ## NEW FEATURES
 
@@ -12,7 +12,10 @@
 
 * A new vignette `vignette("translation", package = "sandpaper")` describes how
   translation of template components works and how to submit new/update
-  translations.
+  translations (added: @zkamvar, #546).
+- A new vignette about data flow `vignette("data-flow", package = "sandpaper")`
+  describes how templating, translations, and lesson metadata flows from
+  {sandpaper} to {varnish} (added: @zkamvar, #553)
 
 ## BUG FIX
 

R/utils-translate.R

@@ -25,7 +25,7 @@ known_languages <- function() {
 
 is_known_language <- function(lang = NULL, warn = FALSE) {
   lang <- lang %||% "en"
-  not_known <- lang %nin% known_languages()
+  not_known <- strsplit(lang, "_")[[1]][1] %nin% known_languages()
   if (not_known && warn) {
     warn_no_language(lang)
   }

tests/testthat/test-translate.R

@@ -34,6 +34,23 @@ test_that("set_language() uses english by default", {
 })
 
 
+test_that("set_language() can use country codes", {
+
+  os <- tolower(Sys.info()[["sysname"]])
+  ver <- getRversion()
+  skip_if(os == "windows" && ver < "4.2")
+
+  expect_silent(set_language("es_AR"))
+  OUTAR <- tr_("OUTPUT")
+  expect_false(identical(OUTAR, "OUTPUT"))
+
+  # the country codes will fall back to language code if they don't exist
+  expect_silent(set_language("es"))
+  expect_equal(tr_("OUTPUT"), OUTAR)
+
+})
+
+
 test_that("is_known_language returns a warning for an unknown language", {
 
   os <- tolower(Sys.info()[["sysname"]])
@@ -61,10 +78,39 @@ test_that("Lessons can be translated with lang setting", {
 
   # Build lesson
   suppressMessages(build_lesson(tmp, preview = FALSE, quiet = TRUE))
+
+  # GENERATED PAGES ------------------------------------------------
+  # Check generated page headers
+  inst_note <- xml2::read_html(fs::path(sitepath, "instructor/instructor-notes.html"))
+  h1_inst <- xml2::xml_find_first(inst_note, "//main/div/h1")
+  expect_equal(
+    xml2::xml_text(h1_inst),
+    withr::with_language("ja", tr_("Instructor Notes"))
+  )
+  expect_false(
+    identical(
+      xml2::xml_text(h1_inst),
+      withr::with_language("en", tr_("Instructor Notes"))
+    )
+  )
+  profiles <- xml2::read_html(fs::path(sitepath, "profiles.html"))
+  h1_profiles <- xml2::xml_find_first(profiles, "//main/div/h1")
+  expect_equal(
+    xml2::xml_text(h1_profiles),
+    withr::with_language("ja", tr_("Learner Profiles"))
+  )
+  expect_false(
+    identical(
+      xml2::xml_text(h1_profiles),
+      withr::with_language("en", tr_("Learner Profiles"))
+    )
+  )
+
 
   # Extract first header (Summary and Setup) from index
   xml <- xml2::read_html(fs::path(sitepath, "index.html"))
   h1_header <- xml2::xml_find_all(xml, "//h1[@class='schedule-heading']")
+  nav_links <- xml2::xml_find_all(xml, "//a[starts-with(@class,'nav-link')]")
 
   # language should be set to japanese
   expect_equal(xml2::xml_attr(xml, "lang"), "ja")
@@ -76,6 +122,21 @@ test_that("Lessons can be translated with lang setting", {
       withr::with_language("ja", tr_("Summary and Setup"))
     )
   )
+  # Navbar has expected text
+  expect_equal(
+    xml2::xml_text(nav_links),
+    withr::with_language("ja", 
+      c(tr_("Key Points"), tr_("Glossary"), tr_("Learner Profiles"))
+    )
+  )
+  expect_false(
+    identical(
+      xml2::xml_text(nav_links),
+      withr::with_language("en", 
+        c(tr_("Key Points"), tr_("Glossary"), tr_("Learner Profiles"))
+      )
+    )
+  )
 
   # Header should no longer be in English
   expect_false(
@@ -84,7 +145,7 @@ test_that("Lessons can be translated with lang setting", {
       withr::with_language("en", tr_("Summary and Setup"))
     )
   )
-
+  
   # aria labels should be translated
   arias <- c("Main Navigation", "Toggle Navigation", "Search", "search button",
     "Lesson Progress", "close menu", "Next Chapter", "anchor", "Back To Top")
@@ -100,6 +161,23 @@ test_that("Lessons can be translated with lang setting", {
   # Episode elements -------------------------------------------------
   # We use here the Instructor view because it is more fully featured
   xml <- xml2::read_html(fs::path(sitepath, "instructor", "introduction.html"))
+  nav_links <- xml2::xml_find_all(xml, "//a[starts-with(@class,'nav-link')]")
+
+  # navbar has expected text
+  expect_equal(
+    xml2::xml_text(nav_links),
+    withr::with_language("ja", 
+      c(tr_("Key Points"), tr_("Instructor Notes"), tr_("Extract All Images"))
+    )
+  )
+  expect_false(
+    identical(
+      xml2::xml_text(nav_links),
+      withr::with_language("en", 
+        c(tr_("Key Points"), tr_("Instructor Notes"), tr_("Extract All Images"))
+      )
+    )
+  )
 
   # overview, objectives, and questions
   overview_card <- xml2::xml_find_first(xml, ".//div[@class='overview card']")

vignettes/data-flow.Rmd

@@ -404,10 +404,83 @@ updated with local data (e.g. the sidebar needs to include headings for the
 current page). 
 
 ```{r globals}
+snd <- asNamespace("sandpaper")
 snd$instructor_globals$get()
 snd$learner_globals$get()
 ```
 
+### Translations
+
+In the majority of the {varnish} templates are keys that need translations that
+are in the format of `{{ translate.ThingInPascalCase }}`:
+
+```{r overview, results="asis", echo = FALSE, comment = ""}
+writeLines("```html")
+writeLines(readLines(system.file("pkgdown/templates/content-overview.html",
+      package = "varnish")))
+writeLines("```")
+```
+
+These variables are in {sandpaper} and are _expected to exist_. They get
+generated by the `set_language()` function, triggered when `build_site()` is
+run. When this gets triggered a new list item called "translate" is added to the
+instructor and learner globals.
+
+```{r set-language}
+snd <- asNamespace("sandpaper")
+length(snd$instructor_globals$get()[["translate"]])
+snd$set_language("en")
+Sys.getenv("LANGUAGE")
+length(snd$instructor_globals$get()[["translate"]])
+```
+
+These variables are passed directly to {varnish} templates, which eventually get
+processed by {whisker}:
+
+```{r whisker}
+whisker::whisker.render("Edit this page: {{ translate.EditThisPage }}",
+  data = snd$instructor_globals$get()
+)
+```
+
+This is key to building lessons in other languages, regardless of your default
+language. The lesson author sets the `lang:` config key to the two-letter
+language code that the lesson is written in. This gets passed to the
+`set_language()` function, which modifies the translations inside the global 
+data. Importantly, it is bound to the calling environment, so when the original
+calling environment exits, the language switches back to your default language.
+
+```{r set-language-es}
+local({
+  snd <- asNamespace("sandpaper")
+  snd$set_language("es")
+  print(Sys.getenv("LANGUAGE"))
+  whisker::whisker.render("Edit this page: {{ translate.EditThisPage }}",
+    data = snd$instructor_globals$get()
+  )
+})
+Sys.getenv("LANGUAGE")
+```
+
+### Translation Variables
+
+There are `r length(snd$instructor_globals$get()[["translate"]])` translations
+generated by `set_language()` that correspond to the following variables in
+{varnish}:
+
+```{r translation-list, results = "asis", echo = FALSE}
+withr::with_language("en", snd$add_varnish_translations())
+res <- glue::glue("| `translate.{names(tr)}` | `{tr}` |", 
+  tr = snd$instructor_globals$get()[["translate"]])
+writeLines(c("| variable | string |\n| --- | --- |", res))
+```
+
+In addition, there are other translations that are inserted _before_ they get
+to {varnish}, which you can find by [searching for `tr_` in
+sandpaper](https://github.com/search?q=repo%3Acarpentries%2Fsandpaper+tr_%28+language%3AR+path%3A%2F%5ER%5C%2F%2F&type=code). 
+
+Some general ones can be found in the `get_codeblock_translations()`, 
+`get_callout_translations()`, and `get_accordion_translations()`, 
 
 ## pkgdown metadata
 
@@ -422,12 +495,23 @@ writeLines("```")
 
 This file is what allows {pkgdown} to recognise that a website needs to be
 built. These variables are compiled into the `pkg` variable that is passed to
-all downstream files from `build_site()`:
+all downstream files from `build_site()`. The important elements we use are
+
+ - `$lang` stores the language variable
+ - `$src_path` stores the source path of the lesson (the `site/` directory, or
+   the location of the `SANDPAPER_SITE` environment variable).
+ - `$dst_path` stores the destination path to the lesson (`site/docs`).
+   **NOTE:** this particular path _could_ be changed in `build_site()` so that
+   we update the name of the path so that it's less confusing. The docs folder
+   was a mechanism for pkgdown to locally deploy the site without having to
+   affect the package structure (it was also a mechanism to serve GitHub pages
+   in the past).
+ - `$meta` a list of items passed on to {varnish}
 
 ```{r pkgdown}
 snd <- asNamespace("sandpaper")
 pkg <- pkgdown::as_pkgdown(snd$path_site(lsn))
-pkg
+pkg[c("lang", "src_path", "dst_path", "meta")]
 ```
 
 Before being sent to be rendered, it goes through one more transformation, which