A multi-language (German/ English) Quarto website

tl;dnr

You can use Quarto project profiles to generate versions of a website in different languages in different subfolders (eg. _site/en and _site/de). If you deploy _site/ creating a navbar item with the href ../en/index.qmd lets you toggle between sites. You’ll also need to implement redirect from the root domain. Limitations: Not quite a complete multi-language implementation (you’ll always start from home after a toggle), preview only possible for one language version at a time.

I recently moved over my website to Quarto. If you don’t know Quarto yet, it’s a new multi-lingual (as in R/ Python/ Julia/ Observable) scientific publishing system. It’s basically expanding on Rmarkdown, making it possible to create beautiful output directly from your data science workflow.

I liked the modern look of out of the box Quarto output and what seemed like streamlined and finetuned workflows. I took re-implementing my website in Quarto as a chance to explore it more deeply and at least for creating websites, I am not going back. The general workflow is well thought out and seemless, congrats RStudio posit. I mostly relied on the official Quarto documentation and this excellent guide on blogging with Quarto.

In the process of moving my homepage, I wanted to tick off another to do and have a website in both German and English.

Quarto Project Profiles

I was quite stuck at first, also because most info on multi-language features of Quarto refer to multiple programming languages - not what I was looking for. But some nice people on Twitter gave me some pointers to a new feature of Quarto. Project Profiles! These had literally been released that day in the pre-release version of Quarto.

They just released support for project profiles which includes some examples of multi-languate website generation. https://t.co/x2QmcRfbKv

— Gordon Shotwell (@gshotwell) September 11, 2022

This means, at the time of writing, if you want to experiment with the workflow I describe here, you need to install the pre-release version.

Profiles are pretty cool - they basically let you set different ways to generate output from your project.

This is useful in many ways but we’ll focus on using project profiles to generate output in two different languages from the same set of files.

Creating language profiles

Profiles work in that you create additional \_quarto.yml files with a profile name next to a basis _quarto.yml file. For an english profile (creating the English version of your website), this would be \_quarto.english.yml.

In the basis _quarto.yml file you need to set which profiles you want to make available to render.

Below you can compare two profile .yml files for English and German and the basis _quarto.yml file. You’ll notice that I set different names for the website title as well as for the navigation items.

_quarto.english.yml

project:
  title: "Mario Angst | Sustainability | Digitalization | Governance"
  output-dir: ./_site/en

website:
  navbar:
    left:
      - href: about.qmd
        text: About me
      - icon: book
        href: publications.qmd
        text: Publications
      - href: software.qmd        
        text: Software
      - href: blog/index.qmd
        text: Blog
    right:
      - href: ../de
        text: Deutsch
      - href: ../en
        text: English

lang: en

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

_quarto.german.yml

project:
  title: "Mario Angst | Nachhaltigkeit | Digitalisierung | Governance"
  output-dir: ./_site/de

website:
  navbar:
    left:
      - href: about.qmd
        text: Über mich
      - href: software.qmd        
        text: Software
      - icon: book
        href: publications.qmd
        text: Publikationen
      - href: blog/index.qmd
        text: Blog (englisch)
    right:
      - href: ../de
        text: Deutsch
      - href: ../en
        text: English
        
lang: de

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

_quarto.yml

project:
  type: website

profile:
  default: english
  group: [english, german]

Previewing and rendering language profiles

With the setup above, we can already render and preview our website in different language versions using (in the terminal):

For english:

quarto preview --profile english

For german:

quarto preview --profile german

This let’s us preview the website with website titles and navigation in the chosen language.

Website content

Up until now, we only changed the language of the scaffolding (title, navigation) of the homepage. How do we create website content in different languages?

This is where the next trick with profiles comes in. You can tell Quarto which parts of a document are in which language. It’s quite simple. Here is for example how my index.qmd file looks like:

index.qmd

::: {when-profile="english"}
Postdoc at the [Digital Society Initiative](https://www.dsi.uzh.ch/de.html) of the University of Zürich

Urban sustainability transformations \
Governance networks \
Digitalization


Project lead [SDGnets\@ZH](https://www.sdgnets.ch/)

Project member ["Government as/is a platform"](https://dizh.ch/en/2022/06/07/government-as-is-a-platform-2/)
:::

::: {when-profile="german"}
Postdoc, [Digitalisierungsinitiative der Universität Zürich](https://www.dsi.uzh.ch/de.html)


Forschung zu 

- nachhaltiger Stadtentwicklung
- Digitalisierung und Nachhaltigkeit
- Governance-Netzwerken

Projektleitung [SDGnets\@ZH](https://www.sdgnets.ch/)

:::

Two languages in one index.qmd document - and you can mark which content should be rendered with which language profile by enclosing content (eg. for German content) using :::{{when-profile="german"}} then adding German content and then closing again with :::

I like this setup for the types of websites Quarto is likely to be used for because this means that your different language versions always live in the same document, making it easy to keep them in sync.

If you now render or preview your website again in a language profile, only the content is included for the language profile you specified. We can now generate two different websites in two different languages.

Combining the two language websites

Up until now, we always generated websites in different languages separate from each other. How do we combine them and make it possible for the user to switch between them?

This is where it gets a bit trickier and where this approach is not at the level of a complete multi-language website as it would be state of the art. Also, this might not generalize, depending on where you publish your page.

Basically, if you were eagle-eyed, you saw that in our language profiles we set a right navbar section like this:

quarto.english.yml

(...)
navbar:
  right:
    - href: ../de
      text: Deutsch
    - href: ../en
      text: English
(...)

We also set the output directory for our language specific websites to two different folders. For english in _quarto.english.yml:

project:
  output-dir: ./_site/en
(...)

For German in _quarto.german.yml:

project:
  output-dir: ./_site/de
(...)

Now, if you publish your website somewhere that lets you specify a folder from where your site is published, you can indicate the _site folder as your publishing folder.

I use Netlify and it’s super easy in this regard - assuming you are are publishing from a Github repository, just specify _site as the folder to publish from as the publish directory under Build settings. The _site folder now contains two subfolders with your two language version and is at the root of your site, eg. marioangst.com. By going to marioangst.com/en, you’ll get the english version. To switch to the German version, what happens when you press “Deutsch” is that the prompt ../de is just command line speak for “Go up one level” (the .. part) and then go to the de folder (the /de part). And we can switch :)!

What is important is that the language toggle implemented in this way always leads the user to the home (index.qmd) of the website. It does not directly switch between subsections of the page, eg. from German publications to English publications. Works fine for a small page, not really suitable for a large one, where you might have to think about some more clever routing/ redirects.

Default language

Now, where should the user land when they visit the root domain (eg. marioangst.com in my case)? This can be approached with different levels of complexity.

• The easiest way (I think) would be to also render one additional language profile at at the root domain. You would need to change the navbar language toggles to ./en respectively ./de only.

• A bit more complicated might be to set up a redirect with your publishing option. With Netlify, this was easiest though. I just included a _redirect file in the _site/ directory like this:

_redirect

/              /en
/en/de              /de
/  /de  302  Language=de

This is a lot cleaner - anyone requesting the root is forwarded to english (my default) version. So if you enter marioangst.com you’ll end up at marioangst.com/en

• The most complex way would be to route the user based on eg. their browser settings. Here’s a start - for giggles, I included something like this in the above Netlify redirect for German.

Don’t forget to render and other caveats

Important with this approach is that you’ll always have to render both language profiles before deploying the page. A simple Make script for your terminal might help here if you edit your page a lot.

Also, this setup will make it possible for you to preview the individual language sites but not the multi-language site. But as the multi-language component is basically a single toggle, I guess that does not matter that much.

I hope this helped and we’ll get to see more Quarto websites in multiple languages soon. Most of the world does not speak English :)! Feedback and more clever ways to do this always welcome.