diff --git a/docs/authoring/language.qmd b/docs/authoring/language.qmd index a8e88534b0..fb5ab8fb9b 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 its resolved localized strings 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. +::: diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index 9dbdb16b27..773717785c 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 >}} + +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. + ## 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. diff --git a/docs/prerelease/1.10/_highlights.qmd b/docs/prerelease/1.10/_highlights.qmd index 24bef0b9fe..b129176c52 100644 --- a/docs/prerelease/1.10/_highlights.qmd +++ b/docs/prerelease/1.10/_highlights.qmd @@ -1 +1,8 @@ -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: + +- 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$ + ```