From 10f161d5786a1be943ac8dacf90f06e35f763b50 Mon Sep 17 00:00:00 2001 From: Will Ceolin Date: Fri, 21 Apr 2023 07:35:02 -0300 Subject: [PATCH] feat(theme): add queryString option to localeDropdown (#8915) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Lorber --- packages/docusaurus-theme-classic/src/options.ts | 1 + packages/docusaurus-theme-classic/src/theme-classic.d.ts | 1 + .../theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx | 3 ++- website/docs/api/themes/theme-configuration.mdx | 1 + website/docs/i18n/i18n-tutorial.mdx | 8 ++++++++ 5 files changed, 13 insertions(+), 1 deletion(-) 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: