Configuration

The goal of this vignette is to show the configuration options that are available in {babelquarto}.

Basic configuration

When you start a {babelquarto} project, from scratch or from an existing project, your _quarto.yml file will contain a number of new options:

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

By default, {babelquarto} will have the following options under the babelquarto key:

languagelinks	Where the menu with the links to other languages will be placed. Can be either sidebar or navbar.
languagecodes	A list with each language defined. Each entry has a name with the language abbreviation (for example en or es. The text key changes the text used for the links to this language.
mainlanguage	The main language of the project.
languages	An array of the additional languages (not including the main language).

In addition to the babelquarto key, you will see language specific keys for title, description and author. These keys allow you to have a specific title, description or author in for each additional language.

Customizing the language menu labels

If you want the choice to be between, say “English” and “Español” rather than “Version in EN” and “Version in ES”, add these fields under the babelquarto/languagecodes key, in _quarto.yml:

babelquarto:
  languagecodes:
  - name: es
    text: "Español"
  - name: en
    text: "English"

Using register_main_language() and register_further_languages() will create the boilertemplate for these fields.

Configure the base URL

If you need to configure a base URL, you can use the usual Quarto field, or use the site_url argument of render_book().

book:
  site-url: https://example.com

website:
  site-url: https://example.com

If you render your multilingual book or website in a CI context, you need will need to set the BABELQUARTO_CI_URL environment variable. See vignette("render-with-ci") for more information.

Translate parts in multilingual books

In multilingual books, if you use parts to structure your book, you can translate the part titles like so:

book:
  chapters:
    - index.qmd
    - part: Foreword
      part-fr: Préface
      chapters:
        - foreword.qmd
    - part: Explore
      part-fr: Explorer
      chapters:
        - intro-explore.qmd
        - data-visualisation.qmd

For each additional language, you can use a part-xx key to translate the part title.

Using profiles for advanced configuration

For more advanced customization, you can use Quarto project profiles. In {babelquarto} we will automatically load a language profile if it exists in the project directory and follows our naming convention. Profile configuration are merged with the main _quarto.yml file.

For example, let’s say you have a project with English as the main language and French as an additional language. When rendering the main English language, {babelquarto} will load the en profile and the fr profile when rendering the French version.

You could for example have different navigation menus for each language:

website:
  navbar:
    title: "My Website"
    left:
      - label: "Home"
        href: "index.qmd"
    right:
      - label: "About"
        href: "about.qmd"

website:
  navbar:
    title: "Mon site web"
    left:
      - label: "Accueil"
        href: "index.qmd"
    right:
      - label: "À propos"
        href: "about.qmd"

Profiles allow for advanced configuration, but a careful read of the profiles documentation is recommended. The main _quarto.yml file will be merged with the profile options and this often needs a careful planning of what keys are put in the different configuration files.

Additional profiles

For complex project, you might want to use additional profiles. When you render a project, you can pass a profile argument to render_book() and render_website() to use additional profiles. The profile will be merged with the main _quarto.yml and the language profile.