[v3] update the back-to-top option to support i18n (#3258)

* [v3] update the back-to-top option to support i18n

* fix eslint sort-keys warning

* avoid displaying undefined as text

* keep `loading`, `placeholder` and `themeSwitch.useOptions` default theme options only for `en` lang

* keep it simpler

* lint

* prettier

---------

Co-authored-by: Dimitri POSTOLOV <dmytropostolov@gmail.com>

Author: 87xie

.changeset/slimy-vans-rush.md

@@ -0,0 +1,5 @@
+---
+'nextra-theme-docs': patch
+---
+
+Update the `backToTop` option in the docs theme configuration to support i18n

.changeset/wild-windows-grow.md

@@ -0,0 +1,5 @@
+---
+'nextra-theme-docs': minor
+---
+
+keep `loading`, `placeholder` and `themeSwitch.useOptions` default theme options only for `en` lang

docs/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.

docs/pages/docs/docs-theme/theme-configuration.mdx

@@ -534,7 +534,11 @@ navigating between headings.
       'React.ReactNode | React.FC',
       'Title of the TOC sidebar. By default it’s “On This Page”.'
     ],
-    ['toc.backToTop', 'boolean', 'Add `Scroll to top` link.']
+    [
+      'toc.backToTop',
+      'React.ReactNode | React.FC',
+      'Text of `Scroll to top` button.'
+    ]
   ]}
 />
 

examples/swr-site/next-env.d.ts

@@ -3,4 +3,4 @@
 /// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

examples/swr-site/theme.config.tsx

@@ -190,6 +190,14 @@ const config: DocsThemeConfig = {
     toggleButton: true
   },
   toc: {
+    backToTop: function BackToTop() {
+      const { locale } = useRouter()
+      return {
+        en: 'Scroll to top',
+        es: 'Desplazarse hacia arriba',
+        ru: 'Перейти наверх'
+      }[locale!]
+    },
     extraContent: (
       <img alt="placeholder cat" src="https://placecats.com/300/200" />
     ),

packages/nextra-theme-docs/src/components/back-to-top.tsx

@@ -1,7 +1,7 @@
 import cn from 'clsx'
 import { Button } from 'nextra/components'
 import { ArrowRightIcon } from 'nextra/icons'
-import type { ComponentProps, ReactElement } from 'react'
+import type { ComponentProps, ReactElement, ReactNode } from 'react'
 
 const SCROLL_TO_OPTIONS = { top: 0, behavior: 'smooth' } as const
 
@@ -18,9 +18,11 @@ const scrollToTop: ComponentProps<'button'>['onClick'] = event => {
 }
 
 export function BackToTop({
+  children,
   className,
   hidden
 }: {
+  children: ReactNode
   className?: string
   hidden: boolean
 }): ReactElement {
@@ -38,7 +40,7 @@ export function BackToTop({
         )
       }
     >
-      Scroll to top
+      {children}
       <ArrowRightIcon
         height="16"
         className="_-rotate-90 _border _rounded-full _border-current"

packages/nextra-theme-docs/src/components/toc.tsx

@@ -122,7 +122,9 @@ export function TOC({ toc, filePath }: TOCProps): ReactElement {
           {renderComponent(themeConfig.toc.extraContent)}
 
           {themeConfig.toc.backToTop && (
-            <BackToTop className={linkClassName} hidden={activeIndex < 2} />
+            <BackToTop className={linkClassName} hidden={activeIndex < 2}>
+              {renderComponent(themeConfig.toc.backToTop)}
+            </BackToTop>
           )}
         </div>
       )}

packages/nextra-theme-docs/src/constants.tsx

@@ -1,5 +1,5 @@
 /* eslint sort-keys: error */
-import { useRouter } from 'next/router'
+import { useRouter } from 'nextra/hooks'
 import { DiscordIcon, GitHubIcon } from 'nextra/icons'
 import { isValidElement } from 'react'
 import type { z } from 'zod'
@@ -20,20 +20,6 @@ export const DEFAULT_LOCALE = 'en-US'
 export type DocsThemeConfig = z.infer<typeof themeSchema>
 export type PartialDocsThemeConfig = z.infer<typeof publicThemeSchema>
 
-const LOADING_LOCALES: Record<string, string> = {
-  'en-US': 'Loading',
-  fr: 'Сhargement',
-  ru: 'Загрузка',
-  'zh-CN': '正在加载'
-}
-
-const PLACEHOLDER_LOCALES: Record<string, string> = {
-  'en-US': 'Search documentation',
-  fr: 'Rechercher documents',
-  ru: 'Поиск документации',
-  'zh-CN': '搜索文档'
-}
-
 export const DEFAULT_THEME: DocsThemeConfig = {
   backgroundColor: {
     dark: '17,17,17',
@@ -164,37 +150,19 @@ export const DEFAULT_THEME: DocsThemeConfig = {
       </span>
     ),
     error: 'Failed to load search index.',
-    loading: function useLoading() {
-      const { locale, defaultLocale = DEFAULT_LOCALE } = useRouter()
-      const text =
-        (locale && LOADING_LOCALES[locale]) || LOADING_LOCALES[defaultLocale]
-      return <>{text}…</>
-    },
-    placeholder: function usePlaceholder() {
-      const { locale, defaultLocale = DEFAULT_LOCALE } = useRouter()
-      const text =
-        (locale && PLACEHOLDER_LOCALES[locale]) ||
-        PLACEHOLDER_LOCALES[defaultLocale]
-      return `${text}…`
-    }
+    loading: 'Loading…',
+    placeholder: 'Search documentation…'
   },
   sidebar: {
     defaultMenuCollapseLevel: 2,
     toggleButton: true
   },
   themeSwitch: {
     component: ThemeSwitch,
-    useOptions() {
-      const { locale } = useRouter()
-
-      if (locale === 'zh-CN') {
-        return { dark: '深色主题', light: '浅色主题', system: '系统默认' }
-      }
-      return { dark: 'Dark', light: 'Light', system: 'System' }
-    }
+    useOptions: { dark: 'Dark', light: 'Light', system: 'System' }
   },
   toc: {
-    backToTop: true,
+    backToTop: 'Scroll to top',
     component: TOC,
     float: true,
     title: 'On This Page'

packages/nextra-theme-docs/src/schemas.ts

@@ -126,7 +126,7 @@ export const themeSchema = /* @__PURE__ */ (() =>
       )
     }),
     toc: z.strictObject({
-      backToTop: z.boolean(),
+      backToTop: z.custom<ReactNode | FC>(...reactNode),
       component: z.custom<ReactNode | FC<TOCProps>>(...reactNode),
       extraContent: z.custom<ReactNode | FC>(...reactNode),
       float: z.boolean(),