Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/authoring/language.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -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.<key>` as an escape hatch, that value wins over Quarto's resolved localization.
:::
8 changes: 8 additions & 0 deletions docs/journals/templates.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 8 additions & 1 deletion docs/prerelease/1.10/_highlights.qmd
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
Quarto v1.10 was just released, nothing to see here -- yet!
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$
```
Loading