chore: cherry-pick commits for v3.10.1 patch release (#11982)

fix(i18n): regression bug: `i18n/<path>` should always use locale key/id, not `htmlLang` (#11979)

packages/docusaurus/src/server/__tests__/i18n.test.ts

@@ -278,7 +278,7 @@ describe('loadI18n', () => {
           defaultLocale: 'fr',
           locales: ['en', 'fr', 'de'],
           localeConfigs: {
-            fr: {label: 'Français', translate: false},
+            fr: {label: 'Français', translate: false, htmlLang: 'fr-FR'},
             en: {translate: true, baseUrl: 'en-EN/whatever/else'},
             de: {translate: false, baseUrl: '/de-DE/'},
           },
@@ -295,7 +295,7 @@ describe('loadI18n', () => {
         fr: {
           label: 'Français',
           direction: 'ltr',
-          htmlLang: 'fr',
+          htmlLang: 'fr-FR',
           calendar: 'gregory',
           path: 'fr',
           translate: false,
@@ -458,7 +458,7 @@ describe('loadI18n', () => {
       direction: 'ltr',
       htmlLang: 'en-US',
       label: 'American English',
-      path: 'en-US',
+      path: 'x1',
       translate: false,
       url: 'https://example.com',
     });

packages/docusaurus/src/server/i18n.ts

@@ -87,14 +87,20 @@ function getDefaultDirection(localeStr: string) {
 }
 
 export function getDefaultLocaleConfig(
+  // Locale "key/identifier"
+  // Can be anything, but usually a country / BCP47 code
   locale: string,
+  // optionally provided in i18n.localConfigs, need to respect BCP47
+  htmlLang?: string,
 ): Omit<I18nLocaleConfig, 'translate' | 'url' | 'baseUrl'> {
   try {
     return {
-      label: getDefaultLocaleLabel(locale),
-      direction: getDefaultDirection(locale),
-      htmlLang: locale,
-      calendar: getDefaultCalendar(locale),
+      label: getDefaultLocaleLabel(htmlLang ?? locale),
+      direction: getDefaultDirection(htmlLang ?? locale),
+      htmlLang: htmlLang ?? locale,
+      calendar: getDefaultCalendar(htmlLang ?? locale),
+      // Fot the i18n/<path>, we don't use htmlLang on purpose
+      // see bug https://github.com/facebook/docusaurus/issues/11952
       path: locale,
     };
   } catch (e) {
@@ -152,7 +158,7 @@ export async function loadI18n({
       I18nLocaleConfig,
       'translate' | 'url' | 'baseUrl'
     > = {
-      ...getDefaultLocaleConfig(localeConfigInput.htmlLang ?? locale),
+      ...getDefaultLocaleConfig(locale, localeConfigInput.htmlLang),
       ...localeConfigInput,
     };