docs(language): document crossref title/prefix localisation (#2006) (#2009)

* docs(language): document crossref title/prefix localisation

* refactor: reword per suggestion

(cherry picked from commit c11a03d)

Co-authored-by: Mickaël Canouil <[email protected]>

Author: github-actions[bot]

docs/authoring/_cross-references-callouts.qmd

@@ -32,4 +32,20 @@ The prefixes for each type of callout are:
 | `important`  | `#imp-` |
 | `caution`    | `#cau-` |
 
-: Prefixes for callout cross-references {#tbl-callout-prefixes}
+: Prefixes for callout cross-references {#tbl-callout-prefixes}
+
+The text used for each callout cross-reference (for example, "Note 1" in "See Note 1...") can be localised by setting `crossref-{nte,tip,wrn,imp,cau}-prefix` under `language:`:
+
+``` yaml
+---
+lang: fr
+language:
+  crossref-nte-prefix: "Note"
+  crossref-tip-prefix: "Astuce"
+  crossref-wrn-prefix: "Avertissement"
+  crossref-imp-prefix: "Important"
+  crossref-cau-prefix: "Mise en garde"
+---
+```
+
+See [Cross-Reference Titles and Prefixes](language.qmd#cross-reference-titles-and-prefixes) for the full localisation pattern, including per-language subkeys.

docs/authoring/cross-reference-options.qmd

@@ -41,6 +41,29 @@ crossref:
 ---
 ```
 
+## Localisation
+
+The `crossref:` keys above override caption titles and reference prefixes for the current document and are language-independent.
+For locale-aware overrides, set the corresponding `crossref-{type}-title` and `crossref-{type}-prefix` keys under `language:` instead.
+These keys plug into Quarto's localisation system, can be scoped per target language, and can live in a project-level `_language.yml` file.
+
+For example, the Spanish equivalent of the snippets above is:
+
+``` yaml
+---
+title: "Mi Documento"
+lang: es
+language:
+  crossref-fig-title: "Figura"
+  crossref-tbl-title: "Tabla"
+  crossref-fig-prefix: "fig."
+  crossref-tbl-prefix: "tbl."
+---
+```
+
+The same `language:` mechanism applies to callouts and to [custom cross-reference kinds](cross-references-custom.qmd).
+See [Cross-Reference Titles and Prefixes](language.qmd#cross-reference-titles-and-prefixes) for the full set of supported keys and the per-language subkeys pattern.
+
 ## Numbering
 
 There are a variety of numbering schemes available for cross-references, including:

docs/authoring/cross-references-custom.qmd

@@ -64,6 +64,37 @@ There are some additional options that give you more control over the appearance
 
 You can find a complete listing of the options available for the `custom` key on the [Cross-Reference Options](/docs/reference/metadata/crossref.qmd#custom) reference page.
 
+## Localisation
+
+Custom cross-reference kinds inherit the same localisation pattern as built-in floats.
+A custom kind with `key: vid` is localised by setting `crossref-vid-title` and `crossref-vid-prefix` under `language:`:
+
+``` yaml
+---
+lang: es
+language:
+  crossref-vid-title: "Vídeo"
+  crossref-vid-prefix: "Vídeo"
+crossref:
+  custom:
+    - kind: float
+      reference-prefix: Video
+      key: vid
+---
+```
+
+The per-language subkeys form also works, which is useful when a single project is rendered in more than one language:
+
+``` yaml
+language:
+  es:
+    crossref-vid-prefix: "Vídeo"
+  fr:
+    crossref-vid-prefix: "Vidéo"
+```
+
+See [Cross-Reference Titles and Prefixes](language.qmd#cross-reference-titles-and-prefixes) for the full pattern.
+
 ## PDF Output
 
 If your output format is `pdf` you'll also need to specify `latex-env`, a name to be used for the float environment wrapped around the element in the intermediate TeX. For example, to use the custom video reference type you could add `latex-env: video`:

docs/authoring/language.qmd

@@ -112,6 +112,42 @@ fr:
   title-block-published: "Mis à jour"
 ```
 
+### Cross-Reference Titles and Prefixes
+
+The same mechanism applies to cross-reference labels.
+Any key of the form `crossref-{type}-title` or `crossref-{type}-prefix` can be set under `language`, where `{type}` is a built-in float (`fig`, `tbl`, `lst`), a theorem environment (`thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`), a callout (`nte`, `tip`, `wrn`, `imp`, `cau`), or a [custom cross-reference kind](cross-references-custom.qmd).
+
+For floats and theorem environments, `crossref-{type}-prefix` falls back to `crossref-{type}-title` when omitted.
+
+For example, to localise figure, table, and equation labels in a Spanish document:
+
+``` yaml
+---
+title: "Mi Documento"
+lang: es
+language:
+  crossref-fig-title: "Figura"
+  crossref-tbl-title: "Tabla"
+  crossref-eq-prefix: "Ecuación"
+---
+```
+
+The pattern above also works for cross-reference keys:
+
+``` yaml
+---
+title: "My Document"
+lang: es
+language:
+  es:
+    crossref-fig-title: "Figura"
+  fr:
+    crossref-fig-title: "Figure"
+---
+```
+
+For per-document overrides that do not depend on `lang`, see [Cross-Reference Options](cross-reference-options.qmd).
+
 ## Custom Translations
 
 You can create and use a custom translation for a new language not supported by Quarto as follows: