Internationalization / Multi-lingual project

[kodonian]

Description

💡 Proposal: Native Support for Multi-Lingual Projects in Quarto

I’d like to propose a clean and scalable approach to support multi-lingual content in Quarto, based on the concept of a “root” project with internationalization-aware structure. This expands on previous discussions in Issue #12864 and a workaround described in May 2025.

Currently, there are two common strategies for managing multi-lingual websites/books/projects in Quarto:

---

✅ Approach 1: Single Project using profiles

Maintain a single project directory and use Quarto’s profiles system to switch between languages. Each chapter is duplicated with different filenames (e.g., Kapitel1.qmd for German, Chapter1.qmd for English), while shared styles, filters, and assets are kept global.

Pros:

• Fully supported in current Quarto versions (e.g. v1.8.11)
• Easy to share filters, themes, and libraries
• Can handle multilingual logic via directives inside .qmd files

Cons:

• Codebase can become cluttered with language variants
• Applying language-specific filters (e.g., for date/number formatting) requires extra complexity
• No built-in awareness of language relationships

---

✅ Approach 2: Separate Project Folders per Language

Use one folder per language (e.g., /de, /en) and link them at a higher-level root project. This allows Quarto to build each language version independently while keeping shared assets in a common location.

Pros:

• Clean separation between languages
• Easier to maintain language-specific logic and filters
• Shared assets (styles, filters, includes) can be placed in a shared/ folder

Cons:

• Updating content across languages can be more tedious
• Requires external tooling or scripting to coordinate multi-language builds

---

Example Configuration

# Root _quarto.yml
project:
  title: "My Project"
  output-dir: docs
  languages: [de, en]

book:
  chapters:
    - index.qmd

# Directory structure
/de
   /_quarto.yml
   /Kapitel1.qmd
/docs
   /de
   /en
   index.html
/en
   /_quarto.yml
   /Chapter1.qmd
index.qmd

🛠 Suggested quarto render Behavior for Multi-Language Projects

When a languages: field is defined in the root _quarto.yml, Quarto could automatically render all defined language subprojects by default when running:

quarto render

To render a single language explicitly, a new flag could be introduced:

quarto render --language de

similar syntax for quarto preview.

This structure would make Quarto a powerful tool for multilingual documentation, reducing the need for scripting workarounds while keeping both content and build logic well-organized.

🌐 Beyond Languages: A Generalized Sub-Project Framework

While this languages: mechanism is primarily motivated by multilingual publishing, the same structural approach could be extended to support other types of sub-projects. For example, authors might wish to maintain different editions (e.g., "student" vs. "instructor"), platform variants (e.g., "web" vs. "PDF"), or regional customizations within the same repository. By generalizing the concept of language-aware subfolders into a subprojects: field, Quarto could offer a consistent and scalable way to manage variations of content under a unified root configuration, enabling quarto render to build all subprojects by default, and --name or --filter flags to target specific ones.

Would love to hear your thoughts or whether something similar is already being considered!

[mcanouil]

@kodonian Thanks but there is an open issue for this already. Making a new discussion will only scatter the information highly increasing the likelihood that it will be lost.

• Multilingual websites / books #275

I'm going to close this as duplicate.

• Multilanguage-support #378

[kodonian]

@mcanouil Your referenced issue is not a discussion item, therefore difficult to find and upvote. On the other hand, it is 3 years old. Here I suggested a solution path as well, please keep it open. Thanks

[mcanouil]

The issue can host the discussion and is about support for multi-lingual project.
Having a separate thread does not help.

therefore difficult to find and upvote.

Add a reaction on the original post as many others already did. GitHub allows to filter/sort based on those.

On the other hand, it is 3 years old.

Opening a new discussion won't make things better in this regard. Time is limited and so is the Quarto team, please avoid pushing.

Here I suggested a solution path as well, please keep it open

Your suggestion is not a solution it's an implementation proposal to "fix" #275

[kodonian]

Dear @mcanouil, your tone is disrespectful, and has been the whole day. I have been a promoter of Quarto but don't think I want to deal with this kind of moderation. If you are not interested in workarounds and suggestions for the community, which cost me hours to work out, then maybe this is not the product I should spend my valuable time with.

cc: @dragonstyle, @jjallaire, @cscheid, @cderv.

[mcanouil]

I did not meant any disrespect, I apologise for that.

I'm only saying to centralise the discussion to the thread/issue already opened.
Nothing more.

edit: We linked to #275 every time there is something on that topic. Making your contribution there, ensure it's going to be seen.