The goal of this vignette is to show how you can start and maintain a new multilingual Quarto project using {babelquarto}. There are two types of projects: a book or a website. We will look at each type separately below.
If you want to turn an existing project into a multilingual project, have a look at vignette("convert")
.
Installing babelquarto
Before you can start a new multilingual project, you need to install {babelquarto}.
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")
Starting a multilingual book
To start a multilingual book, use quarto_multilingual_book()
with the parent_dir
argument to specify where you want to create the project and the project_dir
argument to specify the name of the project. The argument main_language
is used to specify the main language of the project and further_languages
lists all additional languages.
parent_dir <- withr::local_tempdir()
project_dir <- "multilingual_book"
babelquarto::quarto_multilingual_book(
parent_dir = parent_dir,
project_dir = project_dir,
main_language = "en",
further_languages = c("es", "fr")
)
Found quarto! Replacing html engine...
Look at the _quarto.yml
file in the project directory. To get familiar with the configuration, take a look at the example below:
project:
type: book
book:
site-url: https://example.com
title: "multilingual_book"
author: "Firstname Lastname"
date: "11/22/2024"
chapters:
- index.qmd
- intro.qmd
- summary.qmd
- references.qmd
bibliography: references.bib
format:
html:
theme: cosmo
babelquarto:
languagelinks: sidebar
languagecodes:
- name: es
text: "Version in es"
- name: fr
text: "Version in fr"
- name: en
text: "Version in en"
mainlanguage: 'en'
languages: ['es', 'fr']
title-es: title in es
title-fr: title in fr
description-es: description in es
description-fr: description in fr
author-es: author in es
author-fr: author in fr
lang: en
The file structure of the project looks like this:
fs::dir_tree(file.path(parent_dir, project_dir))
/tmp/RtmpoUnilE/filec1f3d839c57/multilingual_book
├── _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
Each Quarto file has a Spanish and a French version. These files aren’t automatically translated and are just copies of the original English version. You will have to provide the translations yourself, or look at {babeldown} for automatic translation. If you look at the index.qmd
file, you’ll see that the French file is called index.fr.qmd
and the Spanish file is called index.es.qmd
.
When you’re ready to render your book, use render_book()
:
babelquarto::render_book(file.path(parent_dir, project_dir))
We end up with three books, that cross-link to each other from the left sidebar. Example.
Starting a multilingual website
To start a multilingual website, use quarto_multilingual_website()
with the parent_dir
argument to specify where you want to create the project and the project_dir
argument to specify the name of the project. The argument main_language
is used to specify the main language of the project and further_languages
lists all additional languages.
parent_dir <- withr::local_tempdir()
project_dir <- "multilingual_website"
babelquarto::quarto_multilingual_website(
parent_dir = parent_dir,
project_dir = project_dir,
main_language = "en",
further_languages = c("es", "fr")
)
Look at the _quarto.yml
file in the project directory. To get familiar with the configuration, take a look at the example below:
project:
type: website
website:
site-url: https://example.com
title: "multilingual_website"
navbar:
left:
- href: index.qmd
text: Home
- about.qmd
format:
html:
theme: cosmo
css: styles.css
toc: true
babelquarto:
languagelinks: navbar
languagecodes:
- name: es
text: "Version in es"
- name: fr
text: "Version in fr"
- name: en
text: "Version in en"
mainlanguage: 'en'
languages: ['es', 'fr']
title-es: title in es
title-fr: title in fr
description-es: description in es
description-fr: description in fr
author-es: author in es
author-fr: author in fr
lang: en
The file structure of the project looks like this:
fs::dir_tree(file.path(parent_dir, project_dir))
/tmp/RtmpoUnilE/filec1f72f9da7e/multilingual_website
├── _quarto.yml
├── about.es.qmd
├── about.fr.qmd
├── about.qmd
├── index.es.qmd
├── index.fr.qmd
├── index.qmd
└── styles.css
Each Quarto file has a Spanish and a French version. These files aren’t automatically translated and are just copies of the original English version. You will have to provide the translations yourself, or look at {babeldown} for automatic translation. If you look at the index.qmd
file, you’ll see that the French file is called index.fr.qmd
and the Spanish file is called index.es.qmd
.
When you’re ready to render your website, use babelquarto::render_website()
:
babelquarto::render_website(file.path(parent_dir, project_dir))
We end up with a multilingual website. Example, source
Previewing your multilingual project
Once you have rendered your project, you will have a _site
or _book
folder in your project. In Quarto you would use quarto preview
to be able to get a look at what you project looks like. Because of the way {babelquarto} operates, this isn’t possible. You can however preview your files using the {servr} package.
You can use servr::httw()
to preview your project.
# For a multilingual website
servr::httw("_site")
# For a multilingual book
servr::httw("_book")
This will show an URL that you can open in your IDE or browser to see your project.
Next steps
Take a deeper dive into the configuration options available in {babelquarto} and have a look at vignette("configuration")
.
If you want to translate your multilingual project using automatic translation with DeepL, you should have a look at babeldown.
If you want to setup your own CI and deploy your website, have a look at vignette("render-with-ci")
.
If you need to personalize the Quarto templates, have a look at vignette("custom-templates")
.