quarto and pandoc use different naming systems for Chinese

[jidanni]

Description

$ dlocate --filename-only -P zh.*y|egrep pandoc\|quarto
/usr/share/pandoc/data/translations/zh-Hans.yaml
/usr/share/pandoc/data/translations/zh-Hant.yaml
/opt/quarto/share/language/_language-zh-TW.yml
/opt/quarto/share/language/_language-zh.yml

In a .qmd file, if I use

• lang: zh-Hant I don't get the zh-TW bindings
• lang: zh-TW I get the bindings, but then I also get:

[WARNING] Could not load translations for zh-TW
  data file translations/zh.yaml not found

[cookesan]

Quarto and Pandoc are using two different translation-resource layers here.

In Quarto's source, Quarto reads its own files from share/language, including _language-zh.yml and _language-zh-TW.yml, and merges language-tag variations when resolving Quarto labels. Pandoc's translation files use the script-oriented names you found, such as zh-Hans.yaml and zh-Hant.yaml.

That means lang: zh-TW can match Quarto's labels while still producing a Pandoc-side warning if Pandoc cannot load the translation file it expects. I would treat these as separate knobs: use the lang value Pandoc needs for document rendering, and if the Quarto UI labels need different wording, provide a custom Quarto language: YAML file based on Quarto's _language-zh*.yml resources.

[cderv]

Thanks for the report. I can reproduce both symptoms, and they're real — two separate interop gaps between Quarto and Pandoc on Chinese.

Why the filenames diverge

Both tools use valid BCP 47. Pandoc ships two files — zh-Hans.yaml and zh-Hant.yaml — with the script-subtag convention the IETF recommends for Chinese. Its zh-Hant.yaml is small (~20 document-structure terms like Figure 圖 and Chapter 章) where regional Traditional vocabulary doesn't diverge, so a single generic file works.

https://github.com/jgm/pandoc/blob/8799ad87b797e67577bc5368580685c3fa8e97fb/data/translations/zh-Hant.yaml

Quarto ships _language-zh.yml (Simplified, default) and _language-zh-TW.yml. The TW file was contributed in #6512 as deliberately Taiwan-specific — the contributor ran OpenCC to convert Simplified→Traditional script, then corrected region-specific vocabulary (程式碼 for code, 檔案 for file, etc.). Our UI file is ~128 lines and includes terms where Taiwan and Hong Kong diverge, so a single generic zh-Hant file was intentionally not shipped.

https://github.com/quarto-dev/quarto-cli/blob/e4b75c1a32902f6d6e01ac62752a5b7d02ec0a12/src/resources/language/_language-zh-TW.yml

Neither naming is wrong per BCP 47 — the gap is that neither tool maps between the two conventions.

The two symptoms

Quarto resolves lang by splitting on - and loading most-general-first, with one special case: bare lang: zh is rewritten to zh-Hans before going to Pandoc.

quarto-cli/src/command/render/pandoc.ts

Lines 1251 to 1254 in e4b75c1

	// If the user provides only `zh` as a lang, disambiguate to 'simplified'
	if (pandocMetadata.lang === "zh") {
	pandocMetadata.lang = "zh-Hans";
	}

No equivalent mapping exists for zh-TW ↔ zh-Hant, so:

• lang: zh-Hant → Quarto has no _language-zh-Hant.yml; UI strings fall back to _language-zh.yml (Simplified, wrong for Traditional readers). Pandoc is fine because it has zh-Hant.yaml.
• lang: zh-TW → Quarto loads its Taiwan strings correctly. Pandoc tries zh-TW.yaml, falls back to zh.yaml, neither exists, emits the warning. Pandoc's fallback is hard-coded to strip to the primary language subtag only, without script inference.

https://github.com/jgm/pandoc/blob/8799ad87b797e67577bc5368580685c3fa8e97fb/src/Text/Pandoc/Translations.hs#L58-L86

Our docs also don't tell users which tag to write — neither zh nor zh-TW nor zh-Hant is called out — which makes this worse.

Tracking

Opened #14416 for the Pandoc-side mapping, #14417 for the Quarto UI fallback (has one design question to settle), and #14418 for the docs. Thanks for the detailed reproduction.