diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
index a298f10760e6..f59ca26a0c81 100644
--- 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
index 7984bb35c0bc..f010df9a8515 100644
--- 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
index 57cd4b72d45f..b89de44e9a5a 100644
--- 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
index e718c9adf473..dfe11bfe8128 100644
--- a/website/docs/api/themes/theme-configuration.mdx
+++ b/website/docs/api/themes/theme-configuration.mdx
@@ -616,6 +616,7 @@ Accepted fields:
| `position` | 'left' \| 'right'
| `'left'` | The side of the navbar this item should appear on. |
| `dropdownItemsBefore` | [LinkLikeItem](#navbar-dropdown)[]
| `[]` | Add additional dropdown items at the beginning of the dropdown. |
| `dropdownItemsAfter` | [LinkLikeItem](#navbar-dropdown)[]
| `[]` | 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
diff --git a/website/docs/i18n/i18n-tutorial.mdx b/website/docs/i18n/i18n-tutorial.mdx
index ab3c403286ab..c66fb976aaae 100644
--- 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: