Convert an existing project

If you want to turn an existing project into a multilingual project, you can use {babelquarto}’s register_main_language() and register_further_languages() functions.

Let’s start with a book whose main language is English.

parent_dir <- withr::local_tempdir()
project_dir <- "babelbook"
quarto_bin <- quarto::quarto_path()
Found quarto! Replacing html engine...
withr::with_dir(parent_dir, {
  sys::exec_wait(
    quarto_bin,
    args = c("create-project", project_dir, "--type", "book")
  )
})

First you’ll need to register the main language in the Quarto configuration:

project_path <- file.path(parent_dir, project_dir)
babelquarto::register_main_language(
  main_language = "en",
  project_path = project_path
)

Then you can add further languages, say Spanish and French:

babelquarto::register_further_languages(
  further_languages = c("es", "fr"),
  project_path = project_path
)

We end up with a multilingual book in English and Spanish. If you look at the _quarto.yml file in the project directory, you’ll see that the main_language key is en and the languages key contains es and fr.

project:
  type: book

book:
  title: "babelbook"
  author: "Norah Jones"
  date: "11/22/2024"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt




babelquarto:
  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

You can now start translating your book into Spanish and French. Each file of you project can be translated by adding a suffix to the file name. For example, the Spanish version of index.md will be in index.es.md and the French version in index.fr.md.

You will have to provide the translations yourself. If you want to translate your multilingual project using automatic translation with DeepL, you should have a look at babeldown.

Next steps

Take a deeper dive into the configuration options available in {babelquarto} and have a look at vignette("configuration").

If you want to deploy your website on continuous integration, have a look at vignette("render-with-ci").

If you need to personalize the quarto templates, have a look at vignette("custom-templates").