From c9c7076ba74806bd94879cd666b9215bf13c1cb1 Mon Sep 17 00:00:00 2001
From: Undermoon1412 <80385295+Undermoon1412@users.noreply.github.com>
Date: Thu, 10 Sep 2026 21:29:21 +0800
Subject: [PATCH] fix: localize Chinese docs links (#5275)

* fix: localize Chinese docs links

* fix(docs): correct layout import order

* test(docs): narrow localized link e2e locator

Signed-off-by: Undermoon1412 <80385295+Undermoon1412@users.noreply.github.com>

---------

Signed-off-by: Undermoon1412 <80385295+Undermoon1412@users.noreply.github.com>
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
---
 frontend/src/app/[lang]/docs/layout.tsx       | 35 ++++++++++---------
 .../components/docs/docs-language-context.tsx | 23 ++++++++++++
 .../docs/localized-mdx-components.tsx         | 11 ++----
 .../tests/e2e/docs-localized-links.spec.ts    | 15 ++++++++
 4 files changed, 60 insertions(+), 24 deletions(-)
 create mode 100644 frontend/src/components/docs/docs-language-context.tsx

diff --git a/frontend/src/app/[lang]/docs/layout.tsx b/frontend/src/app/[lang]/docs/layout.tsx
index c29cdfe32..292fefb8c 100644
--- a/frontend/src/app/[lang]/docs/layout.tsx
+++ b/frontend/src/app/[lang]/docs/layout.tsx
@@ -3,6 +3,7 @@ import "katex/dist/katex.min.css";
 import { getPageMap } from "nextra/page-map";
 import { Layout } from "nextra-theme-docs";
 
+import { DocsLanguageProvider } from "@/components/docs/docs-language-context";
 import { buildLocalizedDocsPageMap } from "@/components/docs/docs-page-map";
 import { Footer } from "@/components/landing/footer";
 import { Header } from "@/components/landing/header";
@@ -21,21 +22,23 @@ export default async function DocLayout({ children, params }) {
   const pageMap = buildLocalizedDocsPageMap(`/${lang}/docs`, pages);
 
   return (
-    <Layout
-      navbar={
-        <Header
-          className="sticky max-w-full px-10"
-          homeURL="/"
-          locale={locale}
-        />
-      }
-      pageMap={pageMap}
-      docsRepositoryBase="https://github.com/bytedance/deer-flow/tree/main/frontend"
-      footer={<Footer className="mt-0" />}
-      i18n={i18n}
-      // ... Your additional layout options
-    >
-      {children}
-    </Layout>
+    <DocsLanguageProvider lang={lang}>
+      <Layout
+        navbar={
+          <Header
+            className="sticky max-w-full px-10"
+            homeURL="/"
+            locale={locale}
+          />
+        }
+        pageMap={pageMap}
+        docsRepositoryBase="https://github.com/bytedance/deer-flow/tree/main/frontend"
+        footer={<Footer className="mt-0" />}
+        i18n={i18n}
+        // ... Your additional layout options
+      >
+        {children}
+      </Layout>
+    </DocsLanguageProvider>
   );
 }
diff --git a/frontend/src/components/docs/docs-language-context.tsx b/frontend/src/components/docs/docs-language-context.tsx
new file mode 100644
index 000000000..36a689ed2
--- /dev/null
+++ b/frontend/src/components/docs/docs-language-context.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+const DocsLanguageContext = createContext<string | undefined>(undefined);
+
+export function DocsLanguageProvider({
+  lang,
+  children,
+}: {
+  lang: string | undefined;
+  children: ReactNode;
+}) {
+  return (
+    <DocsLanguageContext.Provider value={lang}>
+      {children}
+    </DocsLanguageContext.Provider>
+  );
+}
+
+export function useDocsLanguage() {
+  return useContext(DocsLanguageContext);
+}
diff --git a/frontend/src/components/docs/localized-mdx-components.tsx b/frontend/src/components/docs/localized-mdx-components.tsx
index 3c729889c..9f4aa74d8 100644
--- a/frontend/src/components/docs/localized-mdx-components.tsx
+++ b/frontend/src/components/docs/localized-mdx-components.tsx
@@ -1,27 +1,22 @@
 "use client";
 
-import { useParams } from "next/navigation";
 import { Anchor, Cards as NextraCards } from "nextra/components";
 import type { ComponentProps } from "react";
 
 import { cn } from "@/lib/utils";
 
+import { useDocsLanguage } from "./docs-language-context";
 import { localizeDocsHref } from "./localized-links";
 
 const DOCS_LINK_CLASS_NAME =
   "x:text-primary-600 x:underline x:hover:no-underline x:decoration-from-font x:[text-underline-position:from-font]";
 
-function useDocumentLanguage(): string | undefined {
-  const { lang } = useParams<{ lang?: string }>();
-  return lang;
-}
-
 export function LocalizedDocsLink({
   href,
   className,
   ...props
 }: ComponentProps<typeof Anchor>) {
-  const lang = useDocumentLanguage();
+  const lang = useDocsLanguage();
   const localizedHref =
     typeof href === "string" ? localizeDocsHref(href, lang) : href;
 
@@ -38,6 +33,6 @@ export function LocalizedCard({
   href,
   ...props
 }: ComponentProps<typeof NextraCards.Card>) {
-  const lang = useDocumentLanguage();
+  const lang = useDocsLanguage();
   return <NextraCards.Card {...props} href={localizeDocsHref(href, lang)} />;
 }
diff --git a/frontend/tests/e2e/docs-localized-links.spec.ts b/frontend/tests/e2e/docs-localized-links.spec.ts
index 476c00256..035132c32 100644
--- a/frontend/tests/e2e/docs-localized-links.spec.ts
+++ b/frontend/tests/e2e/docs-localized-links.spec.ts
@@ -52,6 +52,21 @@ test.describe("Localized documentation links", () => {
     await expect(page.locator("main h1")).toContainText("Agents and Threads");
   });
 
+  test("localizes Chinese Markdown links in quick start", async ({ page }) => {
+    await page.goto("/zh/docs/application/quick-start");
+
+    const link = page.locator("main p").getByRole("link", { name: "配置" });
+    await expect(link).toHaveCount(1);
+    await expect(link).toHaveAttribute(
+      "href",
+      "/zh/docs/application/configuration",
+    );
+
+    await link.click();
+    await expect(page).toHaveURL(/\/zh\/docs\/application\/configuration$/);
+    await expect(page.locator("main h1")).toContainText("配置");
+  });
+
   test("excludes non-documentation app routes from the docs navigation", async ({
     page,
   }) => {