feat(core): Add i18n.localeConfigs[locale].{url,baseUrl} config options (#11316)

Co-authored-by: slorber <[email protected]>

Author: slorber

.eslintrc.js

@@ -214,7 +214,7 @@ module.exports = {
     ],
     'no-useless-escape': WARNING,
     'no-void': [ERROR, {allowAsStatement: true}],
-    'prefer-destructuring': WARNING,
+    'prefer-destructuring': OFF,
     'prefer-named-capture-group': WARNING,
     'prefer-template': WARNING,
     yoda: WARNING,

packages/docusaurus-plugin-pwa/src/registerSw.ts

@@ -9,12 +9,11 @@ import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import {createStorageSlot} from '@docusaurus/theme-common';
 
 // First: read the env variables (provided by Webpack)
-/* eslint-disable prefer-destructuring */
+
 const PWA_SERVICE_WORKER_URL = process.env.PWA_SERVICE_WORKER_URL!;
 const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES = process.env
   .PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES as unknown as (keyof typeof OfflineModeActivationStrategiesImplementations)[];
 const PWA_DEBUG = process.env.PWA_DEBUG;
-/* eslint-enable prefer-destructuring */
 
 const MAX_MOBILE_WIDTH = 996;
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx

@@ -9,39 +9,88 @@ import React, {type ReactNode} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAlternatePageUtils} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
-import {useHistorySelector} from '@docusaurus/theme-common';
+import {mergeSearchStrings, useHistorySelector} from '@docusaurus/theme-common';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import IconLanguage from '@theme/Icon/Language';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 import type {Props} from '@theme/NavbarItem/LocaleDropdownNavbarItem';
 
 import styles from './styles.module.css';
 
+function useLocaleDropdownUtils() {
+  const {
+    siteConfig,
+    i18n: {localeConfigs},
+  } = useDocusaurusContext();
+  const alternatePageUtils = useAlternatePageUtils();
+  const search = useHistorySelector((history) => history.location.search);
+  const hash = useHistorySelector((history) => history.location.hash);
+
+  const getLocaleConfig = (locale: string) => {
+    const localeConfig = localeConfigs[locale];
+    if (!localeConfig) {
+      throw new Error(
+        `Docusaurus bug, no locale config found for locale=${locale}`,
+      );
+    }
+    return localeConfig;
+  };
+
+  const getBaseURLForLocale = (locale: string) => {
+    const localeConfig = getLocaleConfig(locale);
+    const isSameDomain = localeConfig.url === siteConfig.url;
+    if (isSameDomain) {
+      // Shorter paths if localized sites are hosted on the same domain
+      // This reduces HTML size a bit
+      return `pathname://${alternatePageUtils.createUrl({
+        locale,
+        fullyQualified: false,
+      })}`;
+    }
+    return alternatePageUtils.createUrl({
+      locale,
+      fullyQualified: true,
+    });
+  };
+
+  return {
+    getURL: (locale: string, options: {queryString: string | undefined}) => {
+      // We have 2 query strings because
+      // - there's the current one
+      // - there's one user can provide through navbar config
+      // see https://github.com/facebook/docusaurus/pull/8915
+      const finalSearch = mergeSearchStrings(
+        [search, options.queryString],
+        'append',
+      );
+      return `${getBaseURLForLocale(locale)}${finalSearch}${hash}`;
+    },
+    getLabel: (locale: string) => {
+      return getLocaleConfig(locale).label;
+    },
+    getLang: (locale: string) => {
+      return getLocaleConfig(locale).htmlLang;
+    },
+  };
+}
+
 export default function LocaleDropdownNavbarItem({
   mobile,
   dropdownItemsBefore,
   dropdownItemsAfter,
-  queryString = '',
+  queryString,
   ...props
 }: Props): ReactNode {
+  const utils = useLocaleDropdownUtils();
+
   const {
-    i18n: {currentLocale, locales, localeConfigs},
+    i18n: {currentLocale, locales},
   } = useDocusaurusContext();
-  const alternatePageUtils = useAlternatePageUtils();
-  const search = useHistorySelector((history) => history.location.search);
-  const hash = useHistorySelector((history) => history.location.hash);
-
   const localeItems = locales.map((locale): LinkLikeNavbarItemProps => {
-    const baseTo = `pathname://${alternatePageUtils.createUrl({
-      locale,
-      fullyQualified: false,
-    })}`;
-    // preserve ?search#hash suffix on locale switches
-    const to = `${baseTo}${search}${hash}${queryString}`;
     return {
-      label: localeConfigs[locale]!.label,
-      lang: localeConfigs[locale]!.htmlLang,
-      to,
+      label: utils.getLabel(locale),
+      lang: utils.getLang(locale),
+      to: utils.getURL(locale, {queryString}),
       target: '_self',
       autoAddBaseUrl: false,
       className:
@@ -66,7 +115,7 @@ export default function LocaleDropdownNavbarItem({
         id: 'theme.navbar.mobileLanguageDropdown.label',
         description: 'The label for the mobile language switcher dropdown',
       })
-    : localeConfigs[currentLocale]!.label;
+    : utils.getLabel(currentLocale);
 
   return (
     <DropdownNavbarItem

packages/docusaurus-theme-common/package.json

@@ -46,6 +46,7 @@
   "devDependencies": {
     "@docusaurus/core": "3.8.1",
     "@docusaurus/types": "3.8.1",
+    "@total-typescript/shoehorn": "^0.1.2",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21"
   },

packages/docusaurus-theme-common/src/index.ts

@@ -124,6 +124,8 @@ export {
   useQueryString,
   useQueryStringList,
   useClearQueryString,
+  mergeSearchParams,
+  mergeSearchStrings,
 } from './utils/historyUtils';
 
 export {

packages/docusaurus-theme-common/src/utils/__tests__/historyUtils.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {mergeSearchParams, mergeSearchStrings} from '../historyUtils';
+
+describe('mergeSearchParams', () => {
+  it('can append search params', () => {
+    expect(
+      mergeSearchParams(
+        [
+          new URLSearchParams('?key1=val1&key2=val2'),
+          new URLSearchParams('key2=val2-bis&key3=val3'),
+          new URLSearchParams(''),
+          new URLSearchParams('?key3=val3-bis&key4=val4'),
+        ],
+        'append',
+      ).toString(),
+    ).toBe(
+      'key1=val1&key2=val2&key2=val2-bis&key3=val3&key3=val3-bis&key4=val4',
+    );
+  });
+
+  it('can overwrite search params', () => {
+    expect(
+      mergeSearchParams(
+        [
+          new URLSearchParams('?key1=val1&key2=val2'),
+          new URLSearchParams('key2=val2-bis&key3=val3'),
+          new URLSearchParams(''),
+          new URLSearchParams('?key3=val3-bis&key4=val4'),
+        ],
+        'set',
+      ).toString(),
+    ).toBe('key1=val1&key2=val2-bis&key3=val3-bis&key4=val4');
+  });
+});
+
+describe('mergeSearchStrings', () => {
+  it('can append search params', () => {
+    expect(
+      mergeSearchStrings(
+        [
+          '?key1=val1&key2=val2',
+          'key2=val2-bis&key3=val3',
+          '',
+          '?key3=val3-bis&key4=val4',
+        ],
+        'append',
+      ),
+    ).toBe(
+      '?key1=val1&key2=val2&key2=val2-bis&key3=val3&key3=val3-bis&key4=val4',
+    );
+  });
+
+  it('can overwrite search params', () => {
+    expect(
+      mergeSearchStrings(
+        [
+          '?key1=val1&key2=val2',
+          'key2=val2-bis&key3=val3',
+          '',
+          '?key3=val3-bis&key4=val4',
+        ],
+        'set',
+      ),
+    ).toBe('?key1=val1&key2=val2-bis&key3=val3-bis&key4=val4');
+  });
+
+  it('automatically adds ? if there are params', () => {
+    expect(mergeSearchStrings(['key1=val1'], 'append')).toBe('?key1=val1');
+  });
+
+  it('automatically removes ? if there are no params', () => {
+    expect(mergeSearchStrings([undefined, ''], 'append')).toBe('');
+  });
+});