Multilingual webpages with babelquarto (part 1 of 2)

tl;dr

• Quarto doesn’t support multilingual websites (yet).
• I demonstrate how to create one with the babelquarto R package.
• You can see the example website and check out the source code.

Say hi to babelquarto

Quarto is an amazingly flexible tool connecting the data analysis powers of languages like R, python, and Julia to output formats ranging from PDF to websites. New features are rapidly released, but one that has been lacking so far is support for multilingual websites¹. Fortunately, folks at rOpenSci have stepped up to fill the gap with the babelquarto R package². Here, I demonstrate how to use it to make a simple multilingual website.

Important

There is an issue open for adding multilingual websites to Quarto.

If / when that issue gets resolved, it is likely that the method outlined in this blog post will become obsolete. But for now, this is a good way to create a multilingual website (or book).

Note

You may be interested in my presentation at the 2024 JapanR conference on this same topic.

Getting started

Here, I assume you want to add multilingual support to an existing webpage³. For demonstration purposes, let’s use the default one generated by quarto create project (or quarto_create_project() if using the quarto R package):

library(quarto)
library(babelquarto)
library(fs)

# Create the website in a temporary directory.
temp_dir <- tempdir()

quarto_create_project(
  name = "example",
  type = "website",
  dir = temp_dir
)

Let’s check the contents of the new website:

website_dir <- path(temp_dir, "example")

dir_tree(website_dir)

/tmp/RtmplsCCxQ/example
├── _quarto.yml
├── about.qmd
├── index.qmd
└── styles.css

In subsequent steps we will modify _quarto.yml, so let’s see what it looks like in its default form:

readr::read_lines(path(website_dir, "_quarto.yml")) |>
  cat(sep = "\n")

project:
  type: website

website:
  title: "example"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true

Register languages

The next step is to modify _quarto.yml by registering the main language of the website (in other words, the default language that appears when accessing the main URL). Here, we will register Japanese as the main language:

register_main_language(
  main_language = "ja",
  project_path = website_dir
)

This will modify _quarto.yml:

readr::read_lines(path(website_dir, "_quarto.yml")) |>
  cat(sep = "\n")

project:
  type: website

website:
  title: "example"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true




babelquarto:
  languagecodes:
  - name: ja
    text: "Version in ja"
  mainlanguage: 'ja'
lang: ja

You can see a new key babelquarto: has been added at the end. We’ll get to the details of that in a moment.

Next, let’s add an additional language. You can add as many additional languages as you like, but here we will only add English:

register_further_languages(c("en"), website_dir)

readr::read_lines(path(website_dir, "_quarto.yml")) |>
  cat(sep = "\n")

project:
  type: website

website:
  title: "example"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true




babelquarto:
  languagecodes:
  - name: en
    text: "Version in en"
  - name: ja
    text: "Version in ja"
  mainlanguage: 'ja'
  languages: ['en']
title-en: title in en
description-en: description in en
author-en: author in en
lang: ja

Edit _quarto.yml

So far, babelquarto has generated files and content for us, but the next step is to get our hands dirty and actually edit _quarto.yml.

We will make the following changes:

• Change the text on the language selector from Version in en to English and Version in ja to 日本語.

• Set the English versions of the homepage title, author, and description.

• Simplify the layout of the navbar.

This is what edited version looks like:

readr::read_lines(path(website_dir, "_quarto.yml")) |>
  cat(sep = "\n")

project:
  type: website

website:
  title: "テスト用のサイト"
  navbar:
    left:
      - index.qmd
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true




babelquarto:
  languagecodes:
  - name: en
    text: "English"
  - name: ja
    text: "日本語"
  mainlanguage: 'ja'
  languages: ['en']
title-en: Test Site
description-en: My test website
author-en: Joel Nitta
lang: ja

Add translated files

It bears repeating that babelquarto renders multilingual websites, and does not actually translate any contents. So we need to provide those ourselves.

babelquarto expects the translated files to be named with .<lang> inserted between the original file name and the .qmd extension. For example, the English version of index.qmd is index.en.qmd. In this example, index.qmd has contents in the default language (Japanese).

Once you’ve written out those files, the website folder should look like this:

dir_tree(website_dir)

/tmp/RtmplsCCxQ/example
├── _quarto.yml
├── about.en.qmd
├── about.qmd
├── index.en.qmd
├── index.qmd
└── styles.css

…with (for example) contents like this:

readr::read_lines(path(website_dir, "index.qmd")) |>
  cat(sep = "\n")

---
title: "ホーム"
---

これは Quarto のウェブサイトです。

Quarto のウェブサイトについて詳しく知りたい場合は、<https://quarto.org/docs/websites> をご覧ください。

readr::read_lines(path(website_dir, "index.en.qmd")) |>
  cat(sep = "\n")

---
title: "Home"
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

Render

Next, we need to render the .qmd files to HTML. If you are used to using Quarto, you may expect to do this with quarto render or quarto preview, but those do not work with babelquarto.

Instead, we use babelquarto::render_website().

render_website(project_path = website_dir)


[1/2] about.qmd

[2/2] index.qmd

Output created: _site/index.html


[1/2] about.qmd

[2/2] index.qmd

Output created: _site/index.html

The HTML has been written out to _site/.

Serve

Now we’d like to view the rendered website in a browser. Once again, quarto preview cannot be used here. Instead, use servr::httw().

servr::httw(path(website_dir, "_site"))

Your browser should open a tab with the website shown below:

Example repo

I’ve posted this same example to a repository at https://github.com/joelnitta/example-babelquarto/. The rendered website is exactly what you see above.

What’s next

With this, you should be able to create a simple multilingual website.

In my next post, I will demonstrate some more advanced techniques to control content with Quarto profiles and automating deployment with GitHub Actions.

See you next time!

Footnotes

1. The lang option can be used to change the overall language of a website, but this does not allow selecting from among multiple languages.

2. In this blog post I focus on creating a multilingual webpage. babelquarto can also output multilingual books, but AFAIK the workflow is largely the same.

3. If you are creating a multilingual website from scratch, you may want to use babelquarto::quarto_multilingual_website(), or babelquarto::quarto_multilingual_book() for a book.