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").
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")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/21/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: enThe file structure of the project looks like this:
fs::dir_tree(file.path(parent_dir, project_dir))/tmp/RtmpSkBNmP/filec21364822ba/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.qmdEach 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.
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: enThe file structure of the project looks like this:
fs::dir_tree(file.path(parent_dir, project_dir))/tmp/RtmpSkBNmP/filec211ee79af4/multilingual_website
├── _quarto.yml
├── about.es.qmd
├── about.fr.qmd
├── about.qmd
├── index.es.qmd
├── index.fr.qmd
├── index.qmd
└── styles.cssEach 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
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.
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").