Merge pull request #554 from carpentries/ensure-country-codes

ensure country codes; small refactor of translation strings

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/translations.Rmd

@@ -34,6 +34,9 @@ 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).
+If there is country-specific variation for a language that needs to be added,
+it is not necessary to re-translate everything that is identical in the original
+language file---you only need to translate what is different.
 
 Setting the `lang:` keyword will allow the lesson navigational elements of the
 website template to be presented in the same language as the lesson content _if
@@ -43,7 +46,9 @@ in English.
 This vignette is of interest to those who wish to update translations or add new
 translations. In this vignette I will provide resources for updating and adding
 new languages, the process by which translation happens, and I will outline
-special syntax used in {sandpaper}. ## Resources
+special syntax used in {sandpaper}. 
+
+## Resources
 
 ### Recommended Tools