From a3806e3f5a253c6cae83611478c5b2062c224b1e Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:14:30 +0200 Subject: [PATCH 1/6] docs(language): document quarto.language template namespace --- docs/authoring/language.qmd | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/authoring/language.qmd b/docs/authoring/language.qmd index a8e88534b..f67ea454d 100644 --- a/docs/authoring/language.qmd +++ b/docs/authoring/language.qmd @@ -167,3 +167,37 @@ You can create and use a custom translation for a new language not supported by The `language` option can be specified at a project or document level. Additionally, if you include a `_language.yml` file in the root of your project alongside your `_quarto.yml` config file it will be automatically used. If you create a language translation file please consider contributing it so others can benefit from it. See the documentation on [contributing language translations](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/language) for additional details. + +## Localized Strings in Templates + +{{< prerelease-callout 1.10 >}} + +When you author a custom [Pandoc template](/docs/journals/templates.qmd) or a [template partial](/docs/journals/templates.qmd#template-partials), Quarto exposes the resolved `language:` values to Pandoc template variables under a reserved `quarto.language` namespace. + +Read any localized string with dotted-form template variables: + +``` default +$quarto.language.crossref-fig-title$ +$quarto.language.toc-title-document$ +$quarto.language.section-title-abstract$ +``` + +Values resolve through the full localization chain described above: Quarto's bundled `_language.yml`, then the per-locale file matching `lang:`, then any `language:` overrides set on the document or project. For example, `$quarto.language.crossref-ch-prefix$` resolves to `Chapter` by default, to `Chapitre` with `lang: fr`, and to `チャプター` with `lang: ja`. + +A minimal custom template that uses a localized cross-reference prefix: + +``` {.default filename="my-template.tex"} +\documentclass{article} +\begin{document} +\section*{$quarto.language.crossref-ch-prefix$~1} +$body$ +\end{document} +``` + +The keys available under `quarto.language` are the same keys you can override via the top-level `language:` YAML option, listed in [`_language.yml`](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/language/_language.yml). + +::: callout-note +## Internal namespace + +`quarto.*` is reserved as an internal, Quarto-owned namespace inside Pandoc template variables. The user-facing override path for localized strings remains the top-level `language:` YAML key documented above — the schema does not surface `variables.quarto.*` as a user option. If a document explicitly sets `variables.quarto.language.` as an escape hatch, that value wins over Quarto's resolved localization. +::: From 6f3dc8c14480e36a82a53bf63cc2b2d275fef79c Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:23:33 +0200 Subject: [PATCH 2/6] docs(templates): mention quarto.language partial variables --- docs/journals/templates.qmd | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index 9dbdb16b2..b7b8a65a0 100644 --- a/docs/journals/templates.qmd +++ b/docs/journals/templates.qmd @@ -31,6 +31,14 @@ format: For more complete information about template syntax, see [Template syntax](https://pandoc.org/MANUAL.html#template-syntax). +## Localized Strings + +{{< prerelease-callout 1.10 >}} + +When the document sets [`lang:`](/docs/authoring/language.qmd#lang-option) or [`language:`](/docs/authoring/language.qmd#alternate-language), Quarto exposes the resolved localized strings to your template under the `quarto.language` namespace. For example, the cross-reference figure title is available as `$quarto.language.crossref-fig-title$`, and the document table-of-contents title as `$quarto.language.toc-title-document$`. + +See [Localized Strings in Templates](/docs/authoring/language.qmd#localized-strings-in-templates) for the resolution rules and the full list of available keys. + ## Template Partials Replacing an entire template gives you complete control of the rendered output, but many features of Pandoc and Quarto depend upon code and variables that appear in the built in templates. If you replace the entire template and omit these variables, features will not work properly. From 50c4ec53b5d93a2974a867137c7d0c251162c316 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:28:27 +0200 Subject: [PATCH 3/6] docs(templates): drop colon from lang/language link text for consistency --- docs/journals/templates.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index b7b8a65a0..48c0d12ba 100644 --- a/docs/journals/templates.qmd +++ b/docs/journals/templates.qmd @@ -35,7 +35,7 @@ For more complete information about template syntax, see [Template syntax](https {{< prerelease-callout 1.10 >}} -When the document sets [`lang:`](/docs/authoring/language.qmd#lang-option) or [`language:`](/docs/authoring/language.qmd#alternate-language), Quarto exposes the resolved localized strings to your template under the `quarto.language` namespace. For example, the cross-reference figure title is available as `$quarto.language.crossref-fig-title$`, and the document table-of-contents title as `$quarto.language.toc-title-document$`. +When the document sets [`lang`](/docs/authoring/language.qmd#lang-option) or [`language`](/docs/authoring/language.qmd#alternate-language), Quarto exposes the resolved localized strings to your template under the `quarto.language` namespace. For example, the cross-reference figure title is available as `$quarto.language.crossref-fig-title$`, and the document table-of-contents title as `$quarto.language.toc-title-document$`. See [Localized Strings in Templates](/docs/authoring/language.qmd#localized-strings-in-templates) for the resolution rules and the full list of available keys. From 796572485678e4029c7a4a7f3def356e2f7c931e Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:29:33 +0200 Subject: [PATCH 4/6] docs(prerelease): highlight quarto.language template namespace for 1.10 --- docs/prerelease/1.10/_highlights.qmd | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/prerelease/1.10/_highlights.qmd b/docs/prerelease/1.10/_highlights.qmd index 24bef0b9f..8d3085766 100644 --- a/docs/prerelease/1.10/_highlights.qmd +++ b/docs/prerelease/1.10/_highlights.qmd @@ -1 +1,3 @@ -Quarto v1.10 was just released, nothing to see here -- yet! \ No newline at end of file +Quarto 1.10 includes the following new features: + +- Custom Pandoc templates and [template partials](/docs/journals/templates.qmd#template-partials) can now read Quarto's resolved localized strings (e.g. cross-reference titles, TOC title) via a new `quarto.language` Pandoc template-variable namespace, for example `$quarto.language.crossref-fig-title$`. See [Localized Strings in Templates](/docs/authoring/language.qmd#localized-strings-in-templates). From 051aa26227cf58928d24578df9e318de6460c5c2 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:32:38 +0200 Subject: [PATCH 5/6] docs(prerelease): restructure 1.10 highlight bullet to lead with feature name --- docs/prerelease/1.10/_highlights.qmd | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/prerelease/1.10/_highlights.qmd b/docs/prerelease/1.10/_highlights.qmd index 8d3085766..b129176c5 100644 --- a/docs/prerelease/1.10/_highlights.qmd +++ b/docs/prerelease/1.10/_highlights.qmd @@ -1,3 +1,8 @@ Quarto 1.10 includes the following new features: -- Custom Pandoc templates and [template partials](/docs/journals/templates.qmd#template-partials) can now read Quarto's resolved localized strings (e.g. cross-reference titles, TOC title) via a new `quarto.language` Pandoc template-variable namespace, for example `$quarto.language.crossref-fig-title$`. See [Localized Strings in Templates](/docs/authoring/language.qmd#localized-strings-in-templates). +- New `quarto.language` Pandoc template-variable namespace, exposing Quarto's resolved [localized strings](/docs/authoring/language.qmd#localized-strings-in-templates) to custom templates and [template partials](/docs/journals/templates.qmd#template-partials): + + ``` default + $quarto.language.crossref-fig-title$ + $quarto.language.toc-title-document$ + ``` From 11140daf00ac67e02f357668e6aed049093eecc9 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Wed, 20 May 2026 18:53:24 +0200 Subject: [PATCH 6/6] docs: clarify quarto.language available by default, not gated by lang/language --- docs/authoring/language.qmd | 2 +- docs/journals/templates.qmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authoring/language.qmd b/docs/authoring/language.qmd index f67ea454d..fb5ab8fb9 100644 --- a/docs/authoring/language.qmd +++ b/docs/authoring/language.qmd @@ -172,7 +172,7 @@ If you create a language translation file please consider contributing it so oth {{< prerelease-callout 1.10 >}} -When you author a custom [Pandoc template](/docs/journals/templates.qmd) or a [template partial](/docs/journals/templates.qmd#template-partials), Quarto exposes the resolved `language:` values to Pandoc template variables under a reserved `quarto.language` namespace. +When you author a custom [Pandoc template](/docs/journals/templates.qmd) or a [template partial](/docs/journals/templates.qmd#template-partials), Quarto exposes its resolved localized strings to Pandoc template variables under a reserved `quarto.language` namespace. Read any localized string with dotted-form template variables: diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index 48c0d12ba..773717785 100644 --- a/docs/journals/templates.qmd +++ b/docs/journals/templates.qmd @@ -35,7 +35,7 @@ For more complete information about template syntax, see [Template syntax](https {{< prerelease-callout 1.10 >}} -When the document sets [`lang`](/docs/authoring/language.qmd#lang-option) or [`language`](/docs/authoring/language.qmd#alternate-language), Quarto exposes the resolved localized strings to your template under the `quarto.language` namespace. For example, the cross-reference figure title is available as `$quarto.language.crossref-fig-title$`, and the document table-of-contents title as `$quarto.language.toc-title-document$`. +Quarto exposes its resolved localized strings to your template under the `quarto.language` namespace. The values reflect the document's [`lang`](/docs/authoring/language.qmd#lang-option) (default `en`) and any [`language`](/docs/authoring/language.qmd#alternate-language) overrides. For example, the cross-reference figure title is available as `$quarto.language.crossref-fig-title$`, and the document table-of-contents title as `$quarto.language.toc-title-document$`. See [Localized Strings in Templates](/docs/authoring/language.qmd#localized-strings-in-templates) for the resolution rules and the full list of available keys.