feat(theme): add queryString option to localeDropdown (#8915)

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
facebook · Apr 21, 2023 · 10f161d · 10f161d
1 parent 4a4a8be
commit 10f161d
Show file tree

Hide file tree

Showing 5 changed files with 13 additions and 1 deletion.
diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
@@ -200,6 +200,7 @@ const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('localeDropdown').required(),
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
+  queryString: Joi.string(),
 });
 
 const SearchItemSchema = Joi.object({

diff --git a/packages/docusaurus-theme-classic/src/theme-classic.d.ts b/packages/docusaurus-theme-classic/src/theme-classic.d.ts
@@ -1072,6 +1072,7 @@ declare module '@theme/NavbarItem/LocaleDropdownNavbarItem' {
   export interface Props extends DropdownNavbarItemProps {
     readonly dropdownItemsBefore: LinkLikeNavbarItemProps[];
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
+    readonly queryString?: string;
   }
 
   export default function LocaleDropdownNavbarItem(props: Props): JSX.Element;

diff --git a/packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx
@@ -21,6 +21,7 @@ export default function LocaleDropdownNavbarItem({
   mobile,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  queryString = '',
   ...props
 }: Props): JSX.Element {
   const {
@@ -35,7 +36,7 @@ export default function LocaleDropdownNavbarItem({
       fullyQualified: false,
     })}`;
     // preserve ?search#hash suffix on locale switches
-    const to = `${baseTo}${search}${hash}`;
+    const to = `${baseTo}${search}${hash}${queryString}`;
     return {
       label: localeConfigs[locale]!.label,
       lang: localeConfigs[locale]!.htmlLang,

diff --git a/website/docs/api/themes/theme-configuration.mdx b/website/docs/api/themes/theme-configuration.mdx
@@ -616,6 +616,7 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
+| `queryString` | `string` | `undefined` | The query string to be appended to the URL. |
 
 ```mdx-code-block
 </APITable>

diff --git a/website/docs/i18n/i18n-tutorial.mdx b/website/docs/i18n/i18n-tutorial.mdx
@@ -68,6 +68,14 @@ module.exports = {
 };
 ```
 
+:::tip
+
+You can pass a query parameter that will be appended to the URL when a user changes the locale using the dropdown (e.g. `queryString: '?persistLocale=true'`).
+
+This is useful for implementing an automatic locale detection on your server. For example, you can use this parameter to store the user's preferred locale in a cookie.
+
+:::
+
 ### Start your site {#start-your-site}
 
 Start your localized site in dev mode, using the locale of your choice: