Add i18n in Zetachain docs

add-i18-test.md

@@ -0,0 +1,40 @@
+## work repoter
+
+I am try to reading the nextra/next.js & i18n official docs to add a touch-down button on zetachain docs. Help users can click to switch en & zh, and other languages.
+
+### reading
+- https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/src/components/locale-switch.tsx
+- https://nextra-v2-oe0zrpzjp-shud.vercel.app/docs/guide/i18n
+
+denis dev a demo to help me understand how i18n work, I have been read.
+
+- https://docs-v2-git-feat-i18n.zetachain.app/start/app
+- https://docs-v2-git-feat-i18n.zetachain.app/zh-CN/start/app
+
+### developing
+[2025.11.19 09:29] I have been modify `next.config.js` and `/src/theme.config.tsx` to add i18n languages switch feature. testing in cloud server always downtime, so I use my local pc try again.
+
+[2025.11.19 15:15] in macmini is successfully add i18n. I match the en & zh pages:
+
+- [x] about
+- [x] developers
+- [x] nodes
+- [x] reference
+- [x] start
+- [x] users
+
+I add the nextra LocaleSwitch to switch languages, now is support en & zh.
+
+in `src` add the new file `middleware.js`, will help to match the files path.
+
+every english docs is named `xxx.en-US`, every chinese docs is named `xxx.zh-CN`.
+
+but now have three questions in this branch.
+
+1. <del>the sidebar is not turn with the language switch</del>
+2. <del>when user click someone page, the sidebar is not highlight.</del>
+3. in nextra setting, `index.en-US` or `index.zh-CN` will be redirect to the father path, but the true path is the children. such as view `http://localhost:3001/zh-CN/developers/evm` is 404 not found. I am check the problem, but need some times.
+
+[2025.11.21 10:29] I solve the sidebar highlight issue, add a path compare tool `router.ts` in `src/lib/helpers`. the router.pathname is different from page.route, so need a tool to remove the prefix for locale and make a standard router format.
+
+[2025.11.21 12:56] I solve the sidebar en & zh switch, and make sure the folders and files name is true.

next.config.js

@@ -27,6 +27,11 @@ const baseNextConfig = {
      */
     serverSourceMaps: false,
   },
+  i18n: {
+    locales: ["en-US", "zh-CN"],
+    defaultLocale: "en-US",
+    localeDetection: false,
+  },
   trailingSlash: true,
   basePath: process.env.NEXT_PUBLIC_BASE_PATH,
   // This is required to support PostHog trailing slash API requests
@@ -59,6 +64,12 @@ const baseNextConfig = {
         port: "",
         pathname: "/jmvpciyouqsr/**", // production space id
       },
+      {
+        protocol: "https",
+        hostname: "images.ctfassets.net",
+        port: "",
+        pathname: "/ouogysw2n3om/**", // add new space id for testing
+      },
       {
         protocol: "http",
         hostname: "localhost",

src/components/shared/components/Layout/components/NavigationAccordionLink.tsx

@@ -1,12 +1,13 @@
 import { Accordion, AccordionDetails, AccordionSummary, Typography } from "@mui/material";
+import { isPathMatch, normalizePath } from "~/lib/helpers/router"; //导入工具函数
 import clsx from "clsx";
 import Link from "next/link";
 import { useRouter } from "next/router";
 import { Page } from "nextra";
 import { PropsWithChildren, useEffect, useMemo, useState } from "react";
 import tw, { styled } from "twin.macro";
 
-import { getPageTitle } from "~/lib/helpers/nextra";
+import { getPageTitle,getPageTitleWithLocale } from "~/lib/helpers/nextra";
 
 import { IconDropDown } from "../../Icons";
 
@@ -28,8 +29,18 @@ type NavigationAccordionLinkProps = PropsWithChildren<{
 
 const NavigationAccordion: React.FC<NavigationAccordionLinkProps> = ({ page, children }) => {
   const router = useRouter();
-  const isRouteInAccordion = router.pathname.includes(page.route);
+  //const isRouteInAccordion = router.pathname.includes(page.route);
+  const normalizedPathname = normalizePath(router.asPath || router.pathname);
 
+  // console.log('🔵 当前页面 meta:', {
+  //   route: page.route,
+  //   title: page.meta?.title,
+  //   locale: (page as any).locale,
+  // });
+
+  const normalizedPageRoute = normalizePath(page.route);
+  const isRouteInAccordion = normalizedPathname.startsWith(normalizedPageRoute) || normalizedPathname === normalizedPageRoute;
+
   const [expanded, setExpanded] = useState<string | false>(isRouteInAccordion ? page.route : false);
 
   const handleChange = (route: string) => (_event: React.SyntheticEvent, isExpanded: boolean) =>
@@ -59,7 +70,7 @@ const NavigationAccordion: React.FC<NavigationAccordionLinkProps> = ({ page, chi
             "text-grey-500 dark:text-white": expanded,
           })}
         >
-          {getPageTitle(page)}
+          {getPageTitleWithLocale(page, router.locale)}
         </div>
       </AccordionSummary>
 
@@ -70,8 +81,8 @@ const NavigationAccordion: React.FC<NavigationAccordionLinkProps> = ({ page, chi
 
 export const NavigationAccordionLink: React.FC<NavigationAccordionLinkProps> = ({ page, onClick, isTopLevelPage }) => {
   const router = useRouter();
-  const isRouteSelected = router.pathname === page.route;
-
+  // const isRouteSelected = router.pathname === page.route;
+  const isRouteSelected = isPathMatch(router.asPath || router.pathname, page.route, router);
   if (page.kind !== "Folder") {
     return (
       <Link
@@ -92,7 +103,7 @@ export const NavigationAccordionLink: React.FC<NavigationAccordionLinkProps> = (
         )}
 
         <div className="text-base leading-[130%] sm:text-xs sm:leading-[110%] whitespace-pre-wrap text-ellipsis overflow-hidden">
-          {getPageTitle(page)}
+          {getPageTitleWithLocale(page, router.locale)}
         </div>
       </Link>
     );

src/components/shared/components/Layout/components/NavigationItem.tsx

@@ -1,4 +1,5 @@
 import { ListItem } from "@mui/material";
+import { isPathStartWith, normalizePath } from "~/lib/helpers/router"; //导入工具函数
 import clsx from "clsx";
 import { useRouter } from "next/router";
 import { createElement, useMemo } from "react";
@@ -21,17 +22,30 @@ export const NavigationItem = ({ item, isOpen, withLabel = true, onClick }: Navi
 
   const router = useRouter();
 
+  // const isSelected = useMemo(() => {
+  //   if (!url) {
+  //     return false;
+  //   }
+
+  //   if (router.pathname === "/" || url === "/") {
+  //     return url === router.pathname;
+  //   }
+
+  //   return router.pathname.startsWith(url);
+  // }, [url, router.pathname]);
   const isSelected = useMemo(() => {
     if (!url) {
       return false;
     }
-
-    if (router.pathname === "/" || url === "/") {
-      return url === router.pathname;
+
+    const currentPath = router.asPath || router.pathname;
+
+    if (currentPath === "/" || url === "/") {
+      return normalizePath(currentPath) === normalizePath(url);
     }
-
-    return router.pathname.startsWith(url);
-  }, [url, router.pathname]);
+  
+    return isPathStartWith(currentPath, url, router);
+  }, [url, router.asPath, router.pathname, router]);
 
   return (
     <ListItem

src/components/shared/components/Layout/components/NavigationLayout.tsx

@@ -86,10 +86,17 @@ export const NavigationLayout: React.FC<NavigationLayoutProps> = ({ isMainPage,
                             <List className="w-full">
                               {navSection.children
                                 .filter((page) => page.route !== item.url)
+                                // ✅ 添加去重逻辑：使用 Map 去重，只保留每个 route 的第一个页面
+                                .reduce((acc, page) => {
+                                  if (!acc.find((p) => p.route === page.route)) {
+                                    acc.push(page);
+                                  }
+                                  return acc;
+                                }, [] as typeof navSection.children)
                                 .map((page) => (
                                   <div key={page.route} className="px-3 pl-12 sm:pr-6 pb-3 sm:pb-2">
                                     <NavigationAccordionLink
-                                      key={page.route}
+                                      // ✅ 移除重复的 key（已经在 div 上有 key 了）
                                       page={page}
                                       onClick={closeMobileDrawer}
                                       isTopLevelPage

src/hooks/useSetDirectoriesState.ts

@@ -1,26 +1,164 @@
+// import { getAllPages } from "nextra/context";
+// import { useEffect, useMemo } from "react";
+// import { useRouter } from "next/router";
+// import { useAppDispatch } from "../lib/app.store";
+// import { setDirectories, setPages } from "../lib/directories/directories.redux";
+// import { getDirectories } from "../lib/helpers/nextra";
+
+// export const useSetDirectoriesState = () => {
+//   const allPages = getAllPages();
+//   const router = useRouter();
+//   // ✅ 临时日志：查看页面结构
+//   if (allPages.length > 0) {
+//     console.log('🔵 getAllPages() 返回的页面:', allPages[7]);
+//   }
+//   const { flatDirectories, directoriesByRoute } = useMemo(() => getDirectories(allPages), [allPages]);
+
+//   const dispatch = useAppDispatch();
+
+//   useEffect(() => {
+//     if (!allPages.length) return;
+
+//     dispatch(setPages(allPages));
+//   }, [allPages]);
+
+//   useEffect(() => {
+//     if (!flatDirectories.length || !directoriesByRoute) return;
+
+//     dispatch(setDirectories({ flatDirectories, directoriesByRoute }));
+//   }, [flatDirectories, directoriesByRoute]);
+// };
 import { getAllPages } from "nextra/context";
+import { useRouter } from "next/router";
 import { useEffect, useMemo } from "react";
 
 import { useAppDispatch } from "../lib/app.store";
 import { setDirectories, setPages } from "../lib/directories/directories.redux";
 import { getDirectories } from "../lib/helpers/nextra";
 
 export const useSetDirectoriesState = () => {
-  const allPages = getAllPages();
+  const router = useRouter();  // 添加这一行获取当前 locale
+  const allPages = getAllPages();  
+
+  // useEffect(() => {
+  //   if (allPages.length > 0) {
+  //     console.log('🔵 第一个页面对象结构:', {
+  //       route: allPages[0].route,
+  //       locale: (allPages[0] as any).locale,
+  //       name: (allPages[0] as any).name,
+  //       kind: allPages[0].kind,
+  //     });
+  //     // 打印前几个页面的详细信息
+  //     allPages.slice(0, 3).forEach((page, idx) => {
+  //       console.log(`🔵 页面 ${idx}:`, {
+  //         route: page.route,
+  //         locale: (page as any).locale,
+  //         name: (page as any).name,
+  //         kind: page.kind,
+  //       });
+  //     });
+  //   }
+  // }, [allPages]);
+
+  // 从文件名或 route 中提取 locale
+  const extractLocaleFromPage = (page: typeof allPages[0]): string | null => {
+    // 方法 1: 从 page.locale 属性获取（如果存在）
+    if ('locale' in page && (page as any).locale) {
+      return (page as any).locale;
+    }
+
+    // 方法 2: 从 page.name 中提取（例如 "index.zh-CN" -> "zh-CN"）
+    if ('name' in page && (page as any).name) {
+      const name = (page as any).name as string;
+      const match = name.match(/\.(en-US|zh-CN)(\.|$)/);
+      if (match) {
+        return match[1];
+      }
+    }
+
+    // 方法 3: 从 route 中提取（例如 "/zh-CN/developers/evm" -> "zh-CN"）
+    if (page.route) {
+      const routeMatch = page.route.match(/\/(en-US|zh-CN)(\/|$)/);
+      if (routeMatch) {
+        return routeMatch[1];
+      }
+    }
+
+    // 如果没有找到 locale，返回 null（可能是默认语言或无 locale 的页面）
+    return null;
+  };
+
+  // 新增过滤逻辑（替换原来的日志代码）
+  // 根据当前 locale 过滤页面，避免显示重复内容
+  const filteredPages = useMemo(() => {
+    if (!router.locale || !allPages.length) return allPages;
+
+    // 过滤函数：根据 locale 属性过滤页面
+    const filterByLocale = (pages: typeof allPages, targetLocale: string): typeof allPages => {
+      return pages
+        .map((page) => {
+          if (page.kind === "Folder" && "children" in page) {
+            // 递归过滤子页面
+            const filteredChildren = filterByLocale(page.children, targetLocale);
+
+            // 如果过滤后没有子页面，不显示这个文件夹
+            if (filteredChildren.length === 0) return null;
+
+            return {
+              ...page,
+              children: filteredChildren,
+            };
+          } else {
+            // 从页面对象中提取 locale
+            const pageLocale = extractLocaleFromPage(page);
+
+            // 如果页面有明确的 locale 属性
+            if (pageLocale) {
+              // 如果匹配目标 locale，保留它
+              return pageLocale === targetLocale ? page : null;
+            }
+
+            // 如果页面没有 locale 属性：
+            // - 如果目标是默认语言，保留它（默认语言的页面可能没有 locale 后缀）
+            // - 如果目标不是默认语言，过滤掉它（没有 locale 后缀的页面应该只在默认语言时显示）
+            if (targetLocale === router.defaultLocale) {
+              return page;
+            }
+
+            // 非默认语言时，没有 locale 的页面应该被过滤掉
+            return null;
+          }
+        })
+        .filter((page): page is typeof allPages[0] => page !== null);
+    };
+
+    return filterByLocale(allPages, router.locale);
+  }, [allPages, router.locale, router.defaultLocale]);
 
-  const { flatDirectories, directoriesByRoute } = useMemo(() => getDirectories(allPages), [allPages]);
+  // useEffect(() => {
+  //   console.log('🔵 当前 locale:', router.locale);
+  //   console.log('🔵 所有页面数量:', allPages.length);
+  //   console.log('🔵 过滤后页面数量:', filteredPages.length);
+  //   console.log('🔵 过滤后的第一个页面:', filteredPages[0]?.route, (filteredPages[0] as any)?.locale);
+  // }, [router.locale, allPages.length, filteredPages.length]);
+  // 使用 filteredPages 而不是 allPages
+  const { flatDirectories, directoriesByRoute } = useMemo(
+    () => getDirectories(filteredPages),
+    [filteredPages]
+  );
 
   const dispatch = useAppDispatch();
 
+  // 使用 filteredPages 而不是 allPages
   useEffect(() => {
-    if (!allPages.length) return;
+    if (!filteredPages.length) return;
 
-    dispatch(setPages(allPages));
-  }, [allPages]);
+    dispatch(setPages(filteredPages));
+  }, [filteredPages, dispatch]);
 
   useEffect(() => {
     if (!flatDirectories.length || !directoriesByRoute) return;
 
     dispatch(setDirectories({ flatDirectories, directoriesByRoute }));
   }, [flatDirectories, directoriesByRoute]);
-};
+};