The goal of babelquarto is to render a Quarto multilingual book structured like the rOpenSci dev guide:
- each qmd is present once for the main language,
- and once more for each other language with an extension à la
.es.qmd
Installation
You can install the development version of babelquarto from rOpenSci R-universe:
install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org'))
Or from GitHub with:
# install.packages("pak")
pak::pak("ropensci-review-tools/babelquarto")
Example
Create a starter/example book.
parent_dir <- withr::local_tempdir()
book_dir <- "blop"
babelquarto::quarto_multilingual_book(parent_dir = parent_dir, book_dir = book_dir)
readLines(file.path(parent_dir, book_dir, "_quarto.yml"))
#> [1] "project:" " type: book"
#> [3] "" "book:"
#> [5] " site-url: https://example.com" " title: \"blop\""
#> [7] " author: \"Maëlle Salmon\"" " date: \"7/13/2023\""
#> [9] " chapters:" " - index.qmd"
#> [11] " - intro.qmd" " - summary.qmd"
#> [13] " - references.qmd" ""
#> [15] "bibliography: references.bib" ""
#> [17] "format:" " html:"
#> [19] " theme: cosmo" ""
#> [21] "babelquarto:" " mainlanguage: 'en'"
#> [23] " languages: ['es', 'fr']" "title-es: title in es"
#> [25] "title-fr: title in fr" "description-es: description in es"
#> [27] "description-fr: description in fr" "author-es: author in es"
#> [29] "author-fr: author in fr" "lang: en"
fs::dir_tree(file.path(parent_dir, book_dir))
#> /tmp/RtmpCOL4fU/file73c178bdd45/blop
#> ├── _quarto.yml
#> ├── cover.png
#> ├── index.es.qmd
#> ├── index.fr.qmd
#> ├── index.qmd
#> ├── intro.es.qmd
#> ├── intro.fr.qmd
#> ├── intro.qmd
#> ├── references.bib
#> ├── references.es.qmd
#> ├── references.fr.qmd
#> ├── references.qmd
#> ├── summary.es.qmd
#> ├── summary.fr.qmd
#> └── summary.qmd
babelquarto::render_book(file.path(parent_dir, book_dir))
We end up with three books, that cross-link to each other from the left sidebar. Example.
Note that this does not translate the content! Translation tooling will live in babeldown.
Configure the base URL
Use the usual Quarto field, or use the site_url
argument of babelquarto::render_book()
.
:
book-url: https://example.com site
Content translation
From a book whose main language is English…
parent_dir <- withr::local_tempdir()
book_dir <- "babelbook"
quarto_bin <- quarto::quarto_path()
withr::with_dir(parent_dir, {
sys::exec_wait(
quarto_bin,
args = c("create-project", book_dir, "--type", "book")
)
})
#> [1] 0
- Register languages in the Quarto configuration, for instance
book_path <- file.path(parent_dir, book_dir)
babelquarto::register_main_language(main_language = "en", book_path = book_path)
babelquarto::register_further_languages(further_languages = "es", book_path = book_path)
This is how the config file now looks like:
project:
type: book
book:
title: "babelbook"
author: "Jane Doe"
date: "7/13/2023"
chapters:
- index.qmd
- intro.qmd
- summary.qmd
- references.qmd
bibliography: references.bib
format:
html:
theme: cosmo
pdf:
documentclass: scrreprt
babelquarto:
mainlanguage: 'en'
languages: ['es']
title-es: title in es
description-es: description in es
author-es: author in es
lang: en
- qmd/Rmd files.
bla.qmd
translation in Spanish would live inbla.es.qmd
. See babeldown for getting an automated translation. - parts. The part title translation can be stored in
_quarto.yml
like so:
- part: Building Your Package
part-es: Construyendo tu paquete
chapters:
- pkg_building.Rmd
- pkg_ci.Rmd
- pkg_security.Rmd
If it does not exist, babelquarto falls back to the part title in the main language.
- title, author, description. Their translation can be stored in
_quarto.yml
like so (NOT in thebook
list):
book:
title: Cool book
author: Myself
title-es: Libro genial
author-es: Yo misma
If these fields do not exist, babelquarto falls back to their text in the main language.