Document which BCP 47 `lang` tags activate which translation files

Open Beginner friendly
#14,418 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
66/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Domain
documentation, internationalization, localization

Research direction

Review the language documentation at https://quarto.org/docs/authoring/language.html and inspect the shipped translation files, including _language-sr-Latn.yml. Document each translation file's activating lang values, the script-versus-region distinction, and the subtag-prefix fallback. Done means users can identify the correct tag for Chinese, Serbian, and other listed translations.

Written by the indexing model from the issue text.

Description

documentation

The language docs at https://quarto.org/docs/authoring/language.html state "IETF language tags (BCP 47 standard), like en or en-GB" and list supported languages as prose ("...Chinese, Czech, Danish..."). Nothing tells a user writing a Chinese document which of zh / zh-TW / zh-Hant / zh-Hans will activate which UI translation. Same issue for Serbian — we ship _language-sr-Latn.yml but docs don't mention it.

This ambiguity surfaced in quarto-dev/quarto-cli#14409 where a user couldn't tell whether zh-Hant or zh-TW was the "right" tag for Quarto (answer: zh-TW for our full translations, zh-Hant only for Pandoc's side).

Suggestions

We could:

  • Add a table to the language docs listing each shipped translation file and the lang: values that activate it
  • Briefly explain the BCP 47 script-vs-region subtag distinction and note that both forms are valid — Quarto uses region subtags for Chinese (zh-TW) and Portuguese (pt-BR) but script subtags for Serbian (sr-Latn), reflecting contributed files
  • Note Quarto's subtag-prefix fallback (zh-TW loads zh + zh-TW; fr-CA would load fr + fr-CA if that file existed)
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 8h
Merged PRs (30d)
42

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/quarto-cli

All issues in quarto-dev/quarto-cli

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.