How to manage languages in a PDF Quarto book that has chapters with different languages?

[KleinWurm]

Description

Context

I am trying to write a Quarto book in French but some of its chapter are in English. I expected the book pdf output to follow the "French" specific rules, for example:

• Space between word and "!", "?" or ":",
• Use of « » instead of ""
• Table of content translated to "Table des matières"
• Cross-references Equation -> Équation
• Refences: "edited by" -> "édité par" and "(auth1 and anth2, 2000)" -> "(auth1 et anth2, 2000)"
• Cherry on the top: use of "," (comma) intead of "." (point) as decimal separator

and switch to English rules when the chapter language was specified.

Using instruction from Document Language, I used the file _quarto.yml as follows:

project:
  type: book

book:
  title: "La marmotte"
  chapters:
    - index.qmd
    - en_chapter.qmd
    - fr_chapter.qmd
    - references.qmd

bibliography: references.bib
lang: fr-FR # main language (for references, lof and lot, etc.)

format:
  pdf:
    documentclass: scrreprt
    lof: true

editor: visual

Note: I tried fr-FR (Pandoc > language variable) and fr (lang option) but got the same result.

For the chapters written in another language, I put the following at the top of the chapter file:

---
lang: en-GB # this chapter uses a different language than the main book.
---

I am using Quarto 1.7.31 through RStudio 2025.05.0 Build 496, R version 4.5.1 on Windows 11.

Problem

In the pdf version of the book, the lang argument seems ignored. The titles of TOC, LOF and the references, for example, remain in English. None of the mentionned language specific rules were applied.

I searched the user guide about Quarto books (https://quarto.org/docs/books/ and https://quarto.org/docs/reference/projects/books.html) and I was not able to find a solution.

Questions

My questions are:

1. How to set up Quarto Book language at the project scale and change it on a per-chapter basis?
2. What are the thing automated when the language changes? (ex: from space between word en "!", "?" and ":" to decimal separator).

A reproducible example is available here: https://github.com/KleinWurm/quarto-book-languages-test/tree/2930f17e6f564e8ed492339463e071eb491ae83a

[cderv]

This is a bit tricky but I think I know what happens.

Quarto Book are project - you can write your book in several .qmd files, and Quarto will handle it, including for single file book like PDF output.

What happens internally is that a single .md file is created to be rendered to LaTeX and then PDF.
So when you add a YAML configuration block inside a chapter, some options could override the global one, because in Quarto (and Pandoc) multiple YAML configuration block in a single file are merged;

In the pdf version of the book, the lang argument seems ignored. The titles of TOC, LOF and the references, for example, remain in English. None of the mentionned language specific rules were applied.

So I think your last lang: en-GB in a chapter becomes the main configuration for the whole book.

Pandoc feature to have multiple language content is to use Div Block with lang attributes
https://pandoc.org/MANUAL.html#language-variables

This would mean that your English chapter in a French book should be something like

---
title: English chapter in a french book
---

::: {lang=fr-FR}
> Cette citation est écrite en français 

Et le reste du text aussi. Tout le contenu de ce chapitre est dans le bloc
:::

This would be how Pandoc supports it, and what should work in Quarto. I would expect it to work, and if not I would consider this a problem.

I searched the user guide about Quarto books (quarto.org/docs/books and quarto.org/docs/reference/projects/books.html) and I was not able to find a solution.

Unfortunately, we don't document this anywhere. This is only on Pandoc's manual. So to be documented...

How to set up Quarto Book language at the project scale and change it on a per-chapter basis?

To sum up

• lang in _quarto.yml
• ::: {lang=} block in the chapter

What are the thing automated when the language changes? (ex: from space between word en "!", "?" and ":" to decimal separator).

This is dependent on the output format and Pandoc support. For PDF, the language change is handled through babel and polyglossia. So this would be to see within those tooling.

Thanks a lot for sharing your use case. This got me to look into it. I now wonder if we should

• catch lang in YAML front matter
• Do the Fenced Div creation to wrap the whole chapter content with the lang attribute on it.

This would allow to 'magically' works without knowing this Pandoc's official way. 🤔

[KleinWurm]

What happens internally is that a single .md file is created to be rendered to LaTeX and then PDF.
So when you add a YAML configuration block inside a chapter, some options could override the global one, because in Quarto (and Pandoc) multiple YAML configuration block in a single file are merged;

This is so usefull to know! Many thanks!

[cderv]

Cross-references use the language specified in _quarto.yml but in all the document, that is even in the text wrapped in ::: {lang=en-GB. The following produces "Équation 1.1" in the PDF output instead of "Equation 1.1".

Cross-references are a Quarto feature. And I am afraid that for now, this is a limitation that it will work in only one language... Currently, this feature does not integrate with the one I mentioned from Pandoc.
This would be a feature request - on condition this is possible to be this flexible in handling cross reference.

Thus, for now, I wonder if something can be done using Lua filter or post processing.

• If we were to do the feature, we would probably try in Lua to catch for the div with attribute lang, and based on that we would use the right language file for this section. So doing this kind of think manually could be a workaround for your book. Quite manual but could work (catch the div with attributes => then search for the string to replace).

• Stopping at latex output is also possible. Then post processing the LaTeX file could be done. This is usually useful for editing for some stuff Quarto may not support well when publishing a book. Though, it is also manual and dedicated to the book in question. Not ideal.

So just sharing ideas if it can help and ease the limitation encountered.

Is it require to specify the use of babel or polyglossia using the YAML's argument include-in-header?

It shouldn't... I must acknowledge I don't know exactly when LaTeX should do. You could try on a simple single Quarto PDF document to see if this works. You could try bare pandoc too. or even bare LaTeX to see why this is not working. Using keep-tex: true will allow you to access the intermediate tex to look at it when producing pdf output. I wouldn't expect a user to set in include-in-header the babel stuff are already supposed to be in the template. You should see the command in the intermediate tex file.

Is hyphenation the only part of the automation used? (not a critic, just to be sure of what I need to do while writing :-) )

So I did not get the question. AFAIK this should also be handled by babel in LaTeX based on the config set by Pandoc.

[KleinWurm]

Is hyphenation the only part of the automation used? (not a critic, just to be sure of what I need to do while writing :-) )

So I did not get the question. AFAIK this should also be handled by babel in LaTeX based on the config set by Pandoc.

I am sorry, I try to write it better. In other word, I was wondering if the hyphenation algorithm was isolated from the other automated actions of babel and polyglossia, in order to prevent other automatic modifications, such as the typographical conventions, during the rendering of the pdf.

Sadly I do not have (yet) the knowledge to propose efficient solutions using the tools you mentionned (LUA). I will do my best with the tex file.

Many thanks for you answers! Quarto is an amazing tool and I hope it will become more and more used.

[cderv]

Yeah I understand - Lua can be a pain to enter in.

I would really try to focus on how LaTeX is supposed to work when working with Pandoc lang feature.
Quarto will leverage that Pandoc's feature; We just pass lang to Pandoc.

Cross reference is Quarto only, but this is different, and limited for now for your use case.

[cderv]

I have opened

• [FR] How to manage languages in a PDF Quarto book that has chapters with different languages? #13017

to track idea I got while thinking about this

[mcanouil]

For reference:

• How to set multiple languages with babel? #4000

[KleinWurm]

Thanks for the link!