implement l10n strategy

[zkamvar]

This has been split from #18

As {pkgdown} is moving towards their own implementation of l10n (localisation), we need to think about how this will work practically.

At the moment, they are in the process of fixing the issue via R's internal system for l10n, which involves .po files r-lib/pkgdown#1446 (comment)

I think for l10n, this is largely the way to go because every other blog does something slightly different and we want to be able to use an already existing system instead of reinventing the wheel.

[zkamvar]

a little update on this, it appears that Quarto has reinvented the wheel for their strategy, so when we port to them, we will need to adapt: https://quarto.org/docs/authoring/language.html

At the moment, pkdown's answer is still the most comprehensive... addressing both generated and static translations.

[zkamvar]

Regarding the implementation in pkgdown, the strategy is to use the gettext standard in R, which uses the gettext() function to translate messages. {pkgdown} provides a wrapper to ensure the messages are utf8 encoded:

tr_ <- function(...) {
  enc2utf8(gettext(..., domain = "R-pkgdown"))
}

(Note that this only translates singular phrases. ngettext() is needed for plurals)

In the {pkdown} workflow, all of the templated content is provisioned in a large list that is passed between pkgdown functions. The translations are implemented early on in the creation of this data:

  # Language and translations
  out$lang <- pkg$lang
  out$translate <- list(
    skip = tr_("Skip to contents"),
    toggle_nav = tr_("Toggle navigation"),
    search_for = tr_("Search for"),
    on_this_page = tr_("On this page"),
    source = tr_("Source"),
    abstract = tr_("Abstract"),
    authors = tr_("Authors"),
    version = tr_("Version"),
    examples = tr_("Examples"),
    citation = tr_("Citation")
  )

These variables are compiled to the pkgdown yaml and then passed to the mustache templates.

I was wondering: if gettext() relies on the locale to provide translations, then how does pkgdown know to build a Korean site even in an English locale?

The answer is the LANGUAGE environment variable is set locally before computation:

local_envvar_pkgdown <- function(pkg, scope = parent.frame()) {
  withr::local_envvar(
    IN_PKGDOWN = "true",
    LANGUAGE = pkg$lang,
    .local_envir = scope
  )
}

Note this uses {withr} to ensure the environment variable is set in the right scope.

This gets called in a function called section_init(), which is called at the beginning of the build_site_local() function.

Resources

• R Developer's Guide: Message Translations
• Hadley's instructions for adding a translation to pkgdown
• {potools} R package for simplifying getting started
• {potools} Guide for translators

[zkamvar]

One challenge that I currently face is that all of the site elements are embedded in mustache templates such as

sandpaper/inst/templates/sidebar_item-template.txt

Line 8 in 391dbae

<span class="visually-hidden">Current Chapter</span>

here and in several places in varnish.

In order to implement this, I will either have to do one of two things:

1. find and replace these with variables a la pkgdown translate context or
2. use XPath expressions to replace them because I know where they are semantically.

[zkamvar]

Thanks to the work of @joelnitta in #546 this can now be closed