List supported languages in docs

[emeraldsquirrel]

What version of starlight are you using?

0.24.2

What is your idea?

It would be helpful if the Starlight i18n documentation listed the configuration for all the languages that the Starlight UI is by default translated in.

The second paragraph of https://starlight.astro.build/guides/i18n/#translate-starlights-ui lists the languages by name.

It would be helpful if somewhere in the appendix of this article a default configuration could be included for you to copy + paste from to add supported languages to your configuration. Something like:

const locales = {
  root: { label: 'English', lang: 'en' },              // English
  ar: { label: 'اَلْعَرَبِيَّةُ', lang: 'ar', dir: 'rtl', }, // Arabic
  cs: { label: 'čeština', lang: 'cs' },               // Czech
  da: { label: 'Dansk', lang: 'da' },                 // Danish
  de: { label: 'Deutsch', lang: 'de' },               // German
  es: { label: 'Español', lang: 'es' },               // Spanish
  fa: { label: 'فارسی', lang: 'fa', dir: 'rtl', },    // Persian
  fr: { label: 'Français', lang: 'fr' },              // French
  gl: { label: 'Galego', lang: 'gl' },                 // Galician
  he: { label: 'עִבְרִית', lang: 'he', dir: 'rtl', },    // Hebrew
  hi: { label: 'हिंदी', lang: 'hi' },                    // Hindi
  id: { label: 'Bahasa Indonesia', lang: 'id' },       // Indonesian
  it: { label: 'Italiano', lang: 'it' },              // Italian
  ja: { label: '日本語', lang: 'ja' },                 // Japanese
  ko: { label: '한국어', lang: 'ko' },                 // Korean
  nb: { label: 'Bokmål', lang: 'nb' },                 // Norwegian Bokmål
  nl: { label: 'Nederlands', lang: 'nl' },             // Dutch
  pl: { label: 'Polski', lang: 'pl' },                 // Polish
  // pt                                               // Portuguese
  'pt-br': { label: 'Português do Brasil', lang: 'pt-BR' }, // Brazilian Portuguese
  'pt-pt': { label: 'Português', lang: 'pt-PT' },           // Portugal Portuguese
  ro: { label: 'Limba română', lang: 'ro' },           // Romanian
  ru: { label: 'Русский', lang: 'ru' },                // Russian
  sk: { label: 'Slovenčina', lang: 'sk' },             // Slovak
  sv: { label: 'Svenska', lang: 'sv' },               // Swedish
  tr: { label: 'Türkçe', lang: 'tr' },                // Turkish
  uk: { label: 'Українська', lang: 'uk' },            // Ukrainian
  vi: { label: 'tiếng Việt', lang: 'vi' },             // Vietnamese
  // zh                                                // Chinese
  'zh-cn': { label: '简体中文', lang: 'zh-CN' },          // China Chinese
  'zh-tw': { label: '中華民國國語', lang: 'zh-TW' },       // Taiwan Chinese
};

Note I filled this in myself from the available language codes in https://github.com/withastro/starlight/blob/main/packages/starlight/translations/index.ts and I may not have capitalized the language names properly. I used wikipedia to get the language names. The comment listing the english-name is also extremely useful when reading the code. I also tried to add rtl where appropriate but I may have missed some.

Why is this feature necessary?

Right now people making new starlight installs need to do a lot of legwork to get the configuration boilerplate the way starlight expects it. This would facilitate that for languages starlight already supports.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the suggestion. We actually recently implemented some logic that might mean we can eventually make label optional — it’s possible using JavaScript Intl APIs to get a localized version of a language’s name automatically.

I think we made the assumption that if someone is translating docs into another language, also translating the label appropriately would be possible for them.

[emeraldsquirrel]

I think we made the assumption that if someone is translating docs into another language, also translating the label appropriately would be possible for them.

Some site administrators (Read: me) may opt to list languages they hope to get user contributions for, especially if the parent Starlight UI is already translated. This ties in nicely with Lunaria that can pull Starlight locales. Also with respect to the English language name in the trailing comment, this helps readability for non-native-translator to know which language is which!

[jerrychong25]

Hi @delucis , one extended questions, for Astro framework (Not starlight), where can I find full list of language codes? IT would be great have full tables in documentation pages for easier reference.

Is it having same values as shown in https://github.com/withastro/starlight/blob/main/packages/starlight/translations/index.ts?

[delucis]

Hi @jerrychong25 — I’m not entirely sure what you mean by the language codes Astro supports. Astro’s built-in i18n features are limited to routing and should support all possible language tags.

If you’re looking for somewhere to check what valid language code are more generally, I often use this web app: https://r12a.github.io/app-subtags/

[jerrychong25]

Thanks @delucis ! Will use this link as guideline when doing astro i18n =)