Skip to content

Commit e5850df

Browse files
committed
fix: revert 60 format-language keys back to string-only
PR #14773 widened these keys to anyOf: [string, null] to stop a YAML no-value key (parses as null) from failing schema validation. That traded a caught typo for a worse failure: the label then renders as an empty string instead of falling back to its shipped default, the same symptom #14813 fixes for its five navigation-*-label keys. Nothing in _language.yml or the test suite relies on null clearing a shipped default, and translationsForLang's null-pass-through clause exists for custom/extension keys, not these 60 shipped ones, so the anyOf addition added no expressive power for them. Empty string remains the supported way to clear a shipped default. The 09/07 schema-files fixture asserting null validates has moved to tests/docs/schema-validation/ with a dedicated test that now asserts the opposite; that fixture's directory no longer matches schema-files.test.ts's always-expect-success glob.
1 parent 5437792 commit e5850df

11 files changed

Lines changed: 474 additions & 2054 deletions

File tree

‎llm-docs/localization-architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,7 @@ Steps for every new key:
242242
- **Guard meta writes with `if meta[k] == nil` / `||`.** User-provided metadata or extension defaults must win over the auto-injected localized fallback.
243243
- **Format-native localization (babel, Typst) overlaps Quarto's localization.** For LaTeX `\figurename` etc., babel sets these; Quarto's `\renewcommand` deliberately overrides — so user customization via crossref options reaches LaTeX. For Typst figure captions, Typst's own translation table wins; Quarto only overrides the ref `supplement:` argument.
244244
- **Custom/extension keys under `language:` pass through flat and unnamespaced.** There is no `quarto.extensions.<name>.language.<key>` scheme (#14772/#14773 decided this in favor of the simpler flat form). A scalar or `null`-valued key that is not in `kLanguageDefaultsKeys` still survives `translationsForLang` and, for a locale-variation file, `readLanguageTranslations` — both treat "not an object" as "user or extension defined string" rather than dropping it. Only object-valued keys are treated as locale sub-blocks and excluded from this pass-through.
245+
- **To clear a shipped key's default, set it to `""`, not `null`.** All shipped `format-language` keys in `src/resources/schema/definitions.yml` are plain `string` — `null` fails schema validation for these keys (a YAML key written with nothing after the colon parses as `null`, which is usually a typo, not an intentional clear). This is deliberate: nothing in `_language.yml` or the test suite relies on `null` clearing a shipped default, and the pass-through logic above only exists for custom/extension keys Quarto does not ship. #14813 made the same call for its five `navigation-*-label` keys; #14773 briefly widened 60 shipped keys to `anyOf: [string, null]` to stop the typo case from erroring, but that traded a caught mistake for a worse one — the label silently rendering as an empty string with no fallback — so those 60 keys were reverted back to plain `string`.
245246
- **Adding to `languageFilterParams` is rarely needed.** The bulk `startsWith("crossref-"|"callout-"|"environment-")` clause already exposes most new keys to Lua. Only special-purpose keys (like the `crossref-<type>-prefix = crossref-<type>-title` aliasing) belong in the explicit block.
246247
- **`languageFilterParams` does not write to `format.metadata` or `variables:`.** It only populates filter params. If your template needs the value, use channel 2d (preferred) or 2b.
247248
- **`crossref:` block vs `language:` block are different user-facing surfaces.** Per the [Quarto crossref options docs](https://quarto.org/docs/authoring/cross-reference-options.llms.md) and `src/resources/schema/document-crossref.yml`, the `crossref:` YAML block accepts per-document override of common crossref strings — `fig-title`, `fig-prefix`, `sec-prefix`, `lof-title`, `lst-prefix`, theorem family, etc. Translations / locale overrides for ALL localized strings (including those NOT in the crossref schema) go in the `language:` block instead, using the flat `crossref-*` key form (e.g., `language: { crossref-ch-prefix: "Chapitre" }`).

0 commit comments

Comments
 (0)