This is documentation for internal functions for translation. If you want a
guide to providing translations, please read `vignette("translations", package = "sandpaper")`

## Usage

```
these
establish_translation_vars()
set_language(lang = NULL)
tr_src(from = "varnish", key = NULL)
tr_get(from = "varnish", key = NULL)
tr_varnish(key = NULL)
tr_computed(key = NULL)
```

## Arguments

- lang
a two-letter language code (optionally with a country code). Defaults to

`NULL`

, which falls back to English (the language of the source code).- from
a single character specifying the translation list to fetch. This defaults to "varnish" but can be one of the following:

src

varnish

computed

- key
a single character specifying a specific key to fetch from the translation list. This defaults to

`NULL`

, returning the whole list.

## Value

if `key = NULL`

, a list if `key`

is a single character, the result
will be an unnamed character vector of length 1 representing the value from
that list.

## Details

A page generated from sandpaper is made up of user-provided content wrapped into templated HTML provided by varnish. Since users can provide content in any human language that can be processed by computer, sandpaper must have a method to match the template content to the language of the content. These translations are added to the source of sandpaper by volunteers using the potools package.

Template content strings are stored in the `$translations`

element of the
`these`

global environment variable, which is generated by the
`establish_translation_vars()`

function, which is run every time
sandpaper is loaded. The `$translations`

element consists of three
lists:

`varnish`

: a list of translated strings that are passed directly to varnish`computed`

: a list of translated strings that are incorporated into the HTML content before it is passed to varnish.`src`

: a source list of the above two lists that serves as the source of the translations.

Whenever a lesson is built, the function `set_language()`

will read the
`lang`

item from the `config.yaml`

and apply translations to
`these$translations$varnish`

and `these$translations$computed`

before the
lesson is generated or updated.

### List of Translation Variables

There are 61 translations generated by
`set_language()`

that correspond to the following variables in varnish:

variable | string |

`translate.SkipToMain` | `'Skip to main content'` |

`translate.iPreAlpha` | `'Pre-Alpha'` |

`translate.PreAlphaNote` | `'This lesson is in the pre-alpha phase, which means that it is in early development, but has not yet been taught.'` |

`translate.AlphaNote` | `'This lesson is in the alpha phase, which means that it has been taught once and lesson authors are iterating on feedback.'` |

`translate.iAlpha` | `'Alpha'` |

`translate.BetaNote` | `'This lesson is in the beta phase, which means that it is ready for teaching by instructors outside of the original author team.'` |

`translate.iBeta` | `'Beta'` |

`translate.PeerReview` | `'This lesson has passed peer review.'` |

`translate.InstructorView` | `'Instructor View'` |

`translate.LearnerView` | `'Learner View'` |

`translate.MainNavigation` | `'Main Navigation'` |

`translate.ToggleNavigation` | `'Toggle Navigation'` |

`translate.Menu` | `'Menu'` |

`translate.SearchButton` | `'Search the All In One page'` |

`translate.Setup` | `'Setup'` |

`translate.KeyPoints` | `'Key Points'` |

`translate.InstructorNotes` | `'Instructor Notes'` |

`translate.Glossary` | `'Glossary'` |

`translate.LearnerProfiles` | `'Learner Profiles'` |

`translate.More` | `'More'` |

`translate.LessonProgress` | `'Lesson Progress'` |

`translate.CloseMenu` | `'close menu'` |

`translate.EPISODES` | `'EPISODES'` |

`translate.Home` | `'Home'` |

`translate.HomePageNav` | `'Home Page Navigation'` |

`translate.RESOURCES` | `'RESOURCES'` |

`translate.ExtractAllImages` | `'Extract All Images'` |

`translate.AIO` | `'See all in one page'` |

`translate.DownloadHandout` | `'Download Lesson Handout'` |

`translate.ExportSlides` | `'Export Chapter Slides'` |

`translate.PreviousAndNext` | `'Previous and Next Chapter'` |

`translate.Previous` | `'Previous'` |

`translate.EstimatedTime` | `'Estimated time: {icons$clock} {minutes} minutes'` |

`translate.Next` | `'Next'` |

`translate.NextChapter` | `'Next Chapter'` |

`translate.LastUpdate` | `'Last updated on {updated}'` |

`translate.EditThisPage` | `'Edit this page'` |

`translate.ExpandAllSolutions` | `'Expand All Solutions'` |

`translate.SetupInstructions` | `'Setup Instructions'` |

`translate.DownloadFiles` | `'Download files required for the lesson'` |

`translate.ActualScheduleNote` | `'The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.'` |

`translate.BackToTop` | `'Back To Top'` |

`translate.SpanToTop` | `'<(Back)> To Top'` |

`translate.ThisLessonCoC` | `'This lesson is subject to the <(Code of Conduct)>'` |

`translate.CoC` | `'Code of Conduct'` |

`translate.EditOnGH` | `'Edit on GitHub'` |

`translate.Contributing` | `'Contributing'` |

`translate.Source` | `'Source'` |

`translate.Cite` | `'Cite'` |

`translate.Contact` | `'Contact'` |

`translate.About` | `'About'` |

`translate.MaterialsLicensedUnder` | `'Materials licensed under {license} by the authors'` |

`translate.TemplateLicense` | `'Template licensed under <(CC-BY 4.0)> by {template_authors}'` |

`translate.Carpentries` | `'The Carpentries'` |

`translate.BuiltWith` | `'Built with {sandpaper_link}, {pegboard_link}, and {varnish_link}'` |

`translate.ExpandAllSolutions` | `'Expand All Solutions'` |

`translate.CollapseAllSolutions` | `'Collapse All Solutions'` |

`translate.Collapse` | `'Collapse'` |

`translate.Episodes` | `'Episodes'` |

`translate.GiveFeedback` | `'Give Feedback'` |

`translate.LearnMore` | `'Learn More'` |

In addition, there are 26 translations
that are inserted *before* they get to varnish:

variable | string |

`OUTPUT` | `'OUTPUT'` |

`WARNING` | `'WARNING'` |

`ERROR` | `'ERROR'` |

`Overview` | `'Overview'` |

`Questions` | `'Questions'` |

`Objectives` | `'Objectives'` |

`Callout` | `'Callout'` |

`Challenge` | `'Challenge'` |

`Prereq` | `'Prerequisite'` |

`Checklist` | `'Checklist'` |

`Discussion` | `'Discussion'` |

`Testimonial` | `'Testimonial'` |

`Keypoints` | `'Key Points'` |

`Show me the solution` | `'Show me the solution'` |

`Give me a hint` | `'Give me a hint'` |

`Show details` | `'Show details'` |

`Instructor Note` | `'Instructor Note'` |

`SummaryAndSetup` | `'Summary and Setup'` |

`SummaryAndSchedule` | `'Summary and Schedule'` |

`AllInOneView` | `'All in One View'` |

`PageNotFound` | `'Page not found'` |

`AllImages` | `'All Images'` |

`Anchor` | `'anchor'` |

`Figure` | `'Figure {element}'` |

`ImageOf` | `'Image {i} of {n}: {sQuote(txt)}'` |

`Finish` | `'Finish'` |

## See also

`known_languages()`

for a list of known language codes.

## Examples

```
# When sandpaper is loaded, these functions return English
snd <- asNamespace("sandpaper")
head(snd$tr_varnish())
#> $SkipToMain
#> [1] "Skip to main content"
#>
#> $iPreAlpha
#> [1] "Pre-Alpha"
#>
#> $PreAlphaNote
#> [1] "This lesson is in the pre-alpha phase, which means that it is in early development, but has not yet been taught."
#>
#> $AlphaNote
#> [1] "This lesson is in the alpha phase, which means that it has been taught once and lesson authors are iterating on feedback."
#>
#> $iAlpha
#> [1] "Alpha"
#>
#> $BetaNote
#> [1] "This lesson is in the beta phase, which means that it is ready for teaching by instructors outside of the original author team."
#>
head(snd$tr_computed())
#> $OUTPUT
#> [1] "OUTPUT"
#>
#> $WARNING
#> [1] "WARNING"
#>
#> $ERROR
#> [1] "ERROR"
#>
#> $Overview
#> [1] "Overview"
#>
#> $Questions
#> [1] "Questions"
#>
#> $Objectives
#> [1] "Objectives"
#>
# Setting language to Spanish will translate the computed and varnish
snd$set_language("es")
head(snd$tr_varnish())
#> $SkipToMain
#> [1] "Ir al contenido principal"
#>
#> $iPreAlpha
#> [1] "Pre-Alfa"
#>
#> $PreAlphaNote
#> [1] "Esta lección se encuentra en la fase pre-alfa, lo que significa que está en las primeras etapas de desarrollo, pero aún no se ha enseñado."
#>
#> $AlphaNote
#> [1] "Esta lección se encuentra en la fase alfa, lo que significa que se ha enseñado una vesy las autoras de la lección están trabajando en los comentarios."
#>
#> $iAlpha
#> [1] "Alfa"
#>
#> $BetaNote
#> [1] "Esta lección se encuentra en la fase beta, lo que significa que está lista para enseñarpor instructoras que no son parte del equipo original de autoras"
#>
head(snd$tr_computed())
#> $OUTPUT
#> [1] "SALIDA"
#>
#> $WARNING
#> [1] "ADVERTENCIA"
#>
#> $ERROR
#> [1] "ERROR"
#>
#> $Overview
#> [1] "Hoja de ruta"
#>
#> $Questions
#> [1] "Preguntas"
#>
#> $Objectives
#> [1] "Objetivos"
#>
# The source will remain the same
head(snd$tr_src("varnish"))
#> $SkipToMain
#> [1] "Skip to main content"
#>
#> $iPreAlpha
#> [1] "Pre-Alpha"
#>
#> $PreAlphaNote
#> [1] "This lesson is in the pre-alpha phase, which means that it is in early development, but has not yet been taught."
#>
#> $AlphaNote
#> [1] "This lesson is in the alpha phase, which means that it has been taught once and lesson authors are iterating on feedback."
#>
#> $iAlpha
#> [1] "Alpha"
#>
#> $BetaNote
#> [1] "This lesson is in the beta phase, which means that it is ready for teaching by instructors outside of the original author team."
#>
head(snd$tr_src("computed"))
#> $OUTPUT
#> [1] "OUTPUT"
#>
#> $WARNING
#> [1] "WARNING"
#>
#> $ERROR
#> [1] "ERROR"
#>
#> $Overview
#> [1] "Overview"
#>
#> $Questions
#> [1] "Questions"
#>
#> $Objectives
#> [1] "Objectives"
#>
# Running set_language with no arguments defaults to English
snd$set_language()
head(snd$tr_varnish())
#> $SkipToMain
#> [1] "Skip to main content"
#>
#> $iPreAlpha
#> [1] "Pre-Alpha"
#>
#> $PreAlphaNote
#> [1] "This lesson is in the pre-alpha phase, which means that it is in early development, but has not yet been taught."
#>
#> $AlphaNote
#> [1] "This lesson is in the alpha phase, which means that it has been taught once and lesson authors are iterating on feedback."
#>
#> $iAlpha
#> [1] "Alpha"
#>
#> $BetaNote
#> [1] "This lesson is in the beta phase, which means that it is ready for teaching by instructors outside of the original author team."
#>
head(snd$tr_computed())
#> $OUTPUT
#> [1] "OUTPUT"
#>
#> $WARNING
#> [1] "WARNING"
#>
#> $ERROR
#> [1] "ERROR"
#>
#> $Overview
#> [1] "Overview"
#>
#> $Questions
#> [1] "Questions"
#>
#> $Objectives
#> [1] "Objectives"
#>
```