Skip to contents

Get started

Source: vignettes/babelquarto.qmd

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")
)

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: "12/19/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))
[01;34m/tmp/Rtmp88gHf6/file8ac157b42f1/multilingual_book[0m
├── _quarto.yml
├── [01;35mcover.png[0m
├── 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))
[01;34m/tmp/Rtmp88gHf6/file8ac49491481/multilingual_website[0m
├── _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").