knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-", out.width = "100%" ) library(datalang) my_spec <- system.file("specs/thisweek.yml", package = "datalang") esta_semana <- translate_data(my_spec)
The goal is to help people whose first, or preferred, language is not English. This package aids in translating the data and help files. The hope is to lower the barrier of learning R, and also data analysis.
Even though this package can translate data on the fly, this package is meant to be used inside another R package.
The development version is available on GitHub:
# install.packages("devtools") devtools::install_github("edgararuiz/datalang")
The datalang
package uses a translation spec file for translation. The expected file format is YAML. datalang
uses the YAML file to know which column names, and data values, to change. The same YAML spec file can contain the information needed to produce a help file.
Here is a sample spec file:
df: source: thisweek name: esta_semana variables: day: trans: dia desc: Dia de la semana values: friday: viernes saturday: sábado sunday: domingo morning: trans: manana desc: Temperatura a las 10 AM afternoon: trans: tarde desc: Temperatura a las 3 PM help: name: esta_semana alias: esta_semana title: Un data set de ejemplo description: Tres días de temperaturas tomadas en la mañana y la tarde
So a the data set can go from this:
datalang::thisweek
To this:
esta_semana
The datalang
package includes a simple data set called: thisweek
. The package also has a YAML spec file with the translation.
my_spec <- system.file("specs/thisweek.yml", package = "datalang")
The translate_data()
function can ready the YAML spec file found in the my_spec
file path. It uses that spec to locate the data set, in this case thisweek
, modifies a copy of the data set based on the spec, and outputs a new, translated, data set.
translate_data(my_spec)
Not all of the spec's entries were needed to translate the data. The other entries are useful for creating the help documentation. In datalang
there are two functions that output the help:
create_rd()
- It outputs a character vector with contents that can be saved as an rd file.create_html_help()
- It outputs a character vector with contents that can be saved as an HTML file.There are two options to use datalang
to provide accessibility to your package and data:
A package can be built to focus on translations to a single language. Here are some of the features of this approach:
The translate_folder()
function is a higher level wrapper function that produces the translations and help files. The procedure would be to run translate_folder()
on the package's project folder, and then rebuilt the package. The default arguments have the current expectations:
inst/specs
folder.data
.man
.For a working example of this approach, check out the datos
package. This package is dedicated to translating data sets into Spanish: https://github.com/cienciadedatos/datos.
The goal of this approach will be for the existing package to provide the translated data, and the help files, without becoming bulky with copies of the data. For this approach, datalang
provides a function, called on_attach
, that can be run when the package is attached to the R session.
When the package is loaded, via library()
, then datalang
can check for a language setting, and then use that setting as both a trigger, and the pointer to which language should datalang
translate to. At that point, the translated data set is created and loaded into the R session.
The on_attach()
function can be added to the package's .onAttach()
function, so it's processed when the library is loaded. This is what is currently on a fork of gapminder
:
.onAttach <- function(...) { datalang::on_attach("gapminder") }
Using this fork as an example. The language is set to Spanish by using the LANGUAGE environment variable (Sys.setenv(LANGUAGE = "es")
):
Sys.setenv(LANGUAGE = "es") library(gapminder) #> El lenguaje asignado actualmente es español #> Cargando datos y/o ayuda de los siguientes objetos : #> gapminder >-> paises #> Una nueva función de ayuda fue cargada: ayuda() #> Utilice asi: ayuda(paises)
Because the help documentation is created on-the-fly, it cannot be added to the regular data file that functions such as help()
use. So a new help wrapper function is created that creates an HTML version of the data set, or function, help. If the function, data set, or general topic is not one created by datalang
then the requested topic is passed through to the help()
function in the background.
The help's function name will be set based on the language. So in Spanish, the name will be: ayuda
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.