feat(i18n): prefer `languageCode` translation tables before falling back to key

[chalin]

Hugo currently loads i18n translation tables based only on the language key in the languages map (Lang). This causes a mismatch when a site sets a more specific languageCode but retains a short language key.

Example:

languages:
  pt:
    languageCode: pt-BR

i18n/
├── en.toml # Default language
├── [No pt.toml file exists here on in themes etc.]
└── pt-br.toml

When rendering {{ T "some-key" }} for the pt site, Hugo falls back to en.toml because it looks only for pt.toml, ignoring the declared languageCode: pt-BR even though a matching pt-br.toml file exists.

Proposed behavior

If languages.<LANG_KEY>.languageCode is set:

1. Try loading translations using languageCode.
2. If no matching file exists, fall back to current behavior.

Benefits

The proposed behavior maximizes compatibility with existing behavior, while maximizing utility to site authors. Also it:

• Makes translation lookup consistent with the language declared for the site.
• Supports region-specific translations (pt-BR, pt-PT, etc.) without needing multiple language keys.
• Improves compatibility with themes/modules that ship region-coded translation files (e.g., pt-br.toml, zh-hans.toml).

Related

• Hugo cannot identity correct translation string when multiple variants of a language code is used #7982
• Downstream context: [i18n] Translation IDs are not being resolved for pt-BR or zh-CN, or they are but with warnings open-telemetry/opentelemetry.io#8481

Minimal site for testing

• lang-code-feature-test-site

[jmooring]

Related:

• Use Language.LanguageCode as localization key, falling back to language.Lang #9109
• Add languagePrefix to language config #9404

This issue is part of a higher level concept to provide independent control of:

• Language prefix (the portion of the URL that specifies the language)
• Translation table selection (keep this tied to the language key)
• Locale used to localize pluralization, currencies, dates, numbers, collation, etc.

Somewhere in past discussions someone (probably me) also floated the idea of deprecating Language.LanguageCode in favor of Language.Locale because it is a locale not a language code.