openmanual 0.10.0 → 0.11.0

package/dist/bin.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 import { existsSync } from "node:fs";
-import { basename, dirname, extname, join, parse, relative, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { spawn } from "node:child_process";
-import { access, copyFile, cp, lstat, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { z } from "zod";
 
 //#region src/core/config/schema.ts
@@ -41,6 +41,16 @@ const ThemeSchema = z.object({
 const SearchSchema = z.object({ enabled: z.boolean().optional() });
 const MdxSchema = z.object({ latex: z.boolean().optional() });
 const PageActionsSchema = z.object({ enabled: z.boolean().optional() });
+const I18nLocaleSchema = z.object({
+	code: z.string().min(1),
+	name: z.string().min(1)
+});
+const I18nConfigSchema = z.object({
+	enabled: z.boolean().optional(),
+	defaultLanguage: z.string().optional(),
+	languages: z.array(I18nLocaleSchema).optional(),
+	parser: z.enum(["dot", "dir"]).optional()
+});
 const OpenManualConfigSchema = z.object({
 	name: z.string().min(1),
 	description: z.string().optional(),
@@ -56,7 +66,8 @@ const OpenManualConfigSchema = z.object({
 	theme: ThemeSchema.optional(),
 	search: SearchSchema.optional(),
 	mdx: MdxSchema.optional(),
-	pageActions: PageActionsSchema.optional()
+	pageActions: PageActionsSchema.optional(),
+	i18n: I18nConfigSchema.optional()
 });
 function collectConfiguredSlugs(config) {
 	const slugs = /* @__PURE__ */ new Set();
@@ -68,6 +79,12 @@ function buildTitleMap(config) {
 	if (config.sidebar) for (const group of config.sidebar) for (const page of group.pages) map[page.slug] = page.title;
 	return map;
 }
+function isI18nEnabled(config) {
+	return config.i18n?.enabled === true && (config.i18n.languages?.length ?? 0) > 1;
+}
+function isDirParser(config) {
+	return config.i18n?.parser === "dir";
+}
 
 //#endregion
 //#region src/core/config/loader.ts
@@ -138,7 +155,13 @@ function mergeDefaults(config) {
 		pageActions: {
 			...DEFAULT_CONFIG.pageActions,
 			...config.pageActions
-		}
+		},
+		i18n: config.i18n ? {
+			enabled: config.i18n.enabled ?? false,
+			defaultLanguage: config.i18n.defaultLanguage ?? config.locale ?? "zh",
+			languages: config.i18n.languages ?? [],
+			parser: config.i18n.parser ?? "dot"
+		} : void 0
 	};
 }
 
@@ -271,6 +294,48 @@ figure.shiki > div {
 `;
 }
 
+//#endregion
+//#region src/core/generator/i18n-config.ts
+/**
+* 生成 lib/i18n.ts
+*
+* 使用 fumadocs-core 的 defineI18n 定义多语言配置。
+*/
+function generateI18nConfig(_ctx) {
+	const i18nCfg = _ctx.config.i18n;
+	if (!i18nCfg?.enabled || !i18nCfg.languages || i18nCfg.languages.length < 2) throw new Error("generateI18nConfig called but i18n is not properly configured");
+	return `import { defineI18n } from 'fumadocs-core/i18n';
+
+export const i18n = defineI18n({
+  defaultLanguage: '${i18nCfg.defaultLanguage ?? _ctx.config.locale ?? "zh"}',
+  languages: [${i18nCfg.languages.map((l) => `'${l.code}'`).join(", ")}],${i18nCfg.parser === "dir" ? `\n  parser: 'dir',` : ""}
+});
+`;
+}
+
+//#endregion
+//#region src/core/generator/i18n-ui.ts
+/**
+* 生成 lib/i18n-ui.ts
+*
+* 使用 fumadocs-ui 的 defineI18nUI 定义各语言的 UI 翻译（显示名称等）。
+*/
+function generateI18nUI(_ctx) {
+	const i18nCfg = _ctx.config.i18n;
+	if (!i18nCfg?.languages || i18nCfg.languages.length === 0) throw new Error("generateI18nUI called but no languages configured");
+	return `import { defineI18nUI } from 'fumadocs-ui/i18n';
+import { i18n } from '@/lib/i18n';
+
+export const i18nUI = defineI18nUI(i18n, {
+  translations: {
+${i18nCfg.languages.map((lang) => `    '${lang.code}': {
+      displayName: '${lang.name}',
+    }`).join(",\n")}
+  },
+});
+`;
+}
+
 //#endregion
 //#region src/core/generator/layout.ts
 const IMAGE_EXTENSIONS = [
@@ -297,6 +362,7 @@ function resolveLogoPaths(logo) {
 function generateLayout(ctx) {
 	const { config } = ctx;
 	const logo = config.navbar?.logo ?? config.name;
+	const isI18n = config.i18n?.enabled === true;
 	let logoProps;
 	if (typeof logo === "string" && isImagePath(logo)) logoProps = `type="image" src="${logo}" alt="${config.name}"`;
 	else if (typeof logo === "object") {
@@ -304,6 +370,18 @@ function generateLayout(ctx) {
 		if (light === dark) logoProps = `type="image" src="${light}" alt="${config.name}"`;
 		else logoProps = `type="image" srcLight="${light}" srcDark="${dark}" alt="${config.name}"`;
 	} else logoProps = `type="text" text="${logo}"`;
+	if (isI18n) return `import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+import type { ReactNode } from 'react';
+import { NavLogo } from 'openmanual/components/nav-layout';
+
+export function baseOptions(_locale: string): BaseLayoutProps {
+  return {
+    nav: {
+      title: <NavLogo ${logoProps} /> as ReactNode,
+    },
+  };
+}
+`;
 	return `import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 import type { ReactNode } from 'react';
 import { NavLogo } from 'openmanual/components/nav-layout';
@@ -320,7 +398,17 @@ export function baseOptions(): BaseLayoutProps {
 
 //#endregion
 //#region src/core/generator/lib-source.ts
-function generateLibSource() {
+function generateLibSource(ctx) {
+	if (ctx.config.i18n?.enabled === true) return `import { docs } from '@/.source/server';
+import { loader } from 'fumadocs-core/source';
+import { i18n } from '@/lib/i18n';
+
+export const source = loader({
+  baseUrl: '/',
+  source: docs.toFumadocsSource(),
+  i18n,
+});
+`;
 	return `import { docs } from '@/.source/server';
 import { loader } from 'fumadocs-core/source';
 
@@ -339,6 +427,41 @@ export { Mermaid } from 'openmanual/components/mermaid';
 `;
 }
 
+//#endregion
+//#region src/core/generator/middleware.ts
+/**
+* 生成 middleware.ts（或 proxy.ts）
+*
+* 使用自定义的轻量 i18n 中间件，仅处理：
+* 1. 根路径 / → 重定向到默认语言（如 /zh）
+* 2. 其他所有请求（包括静态资源）→ 直接放行
+*
+* 注意：Next.js 16 已废弃 middleware 推荐使用 proxy，
+* 但 fumadocs-core 尚未提供 createI18nProxy，
+* 因此使用自定义实现避免 createI18nMiddleware 拦截静态资源导致 404。
+*/
+function generateMiddleware(_ctx) {
+	return `import { NextResponse } from 'next/server';
+
+const defaultLanguage = '${_ctx.config.i18n?.defaultLanguage ?? _ctx.config.locale ?? "zh"}';
+
+export default function middleware(request: Request): NextResponse | undefined {
+  const { pathname } = new URL(request.url);
+
+  // 仅处理根路径重定向，其他请求（含静态资源）放行
+  if (pathname === '/') {
+    return NextResponse.redirect(new URL('/' + defaultLanguage, request.url));
+  }
+
+  return undefined;
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon\\.ico).*)'],
+};
+`;
+}
+
 //#endregion
 //#region src/core/generator/next-config.ts
 function generateNextConfig(ctx) {
@@ -364,7 +487,7 @@ export default withMDX(config);
 //#endregion
 //#region src/core/generator/package-json.ts
 function getOpenManualVersion() {
-	return "0.10.0";
+	return "0.11.0";
 }
 function generatePackageJson(ctx) {
 	const openmanualVersion = getOpenManualVersion();
@@ -408,6 +531,10 @@ function generatePackageJson(ctx) {
 function generatePage(_ctx) {
 	const isStrict = _ctx.config.contentPolicy !== "all";
 	const pageActionsEnabled = _ctx.config.pageActions?.enabled !== false;
+	if (_ctx.config.i18n?.enabled === true) return generatePageI18n(_ctx, isStrict, pageActionsEnabled);
+	return generatePageSingle(_ctx, isStrict, pageActionsEnabled);
+}
+function generatePageSingle(_ctx, isStrict, pageActionsEnabled) {
 	const allowedSlugsSnippet = isStrict ? `
 const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.config)])});
 
@@ -481,6 +608,94 @@ export function generateStaticParams() {
 }`}
 `;
 }
+function generatePageI18n(_ctx, isStrict, pageActionsEnabled) {
+	const allowedSlugsSnippet = isStrict ? `
+const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.config)])});
+
+function isAllowed(slug: string[] | undefined): boolean {
+  if (allowedSlugs.size === 0) return true;
+  const key = slug ? slug.join('/') : 'index';
+  return allowedSlugs.has(key);
+}
+` : "";
+	return `import { source } from '@/lib/source';
+import { notFound } from 'next/navigation';
+import { DocsPage, DocsBody, DocsTitle, DocsDescription } from 'fumadocs-ui/page';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { Steps, Step } from 'fumadocs-ui/components/steps';
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Files, File, Folder } from 'fumadocs-ui/components/files';
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { TypeTable } from 'fumadocs-ui/components/type-table';
+import { Mermaid } from '@/components/mermaid';
+import { Callout, CalloutTitle, CalloutDescription } from '@/components/callout';${pageActionsEnabled ? "\nimport { PageActions } from '@/components/page-actions';" : ""}
+${allowedSlugsSnippet}
+export default async function Page({ params }: { params: Promise<{ slug?: string[]; lang: string }> }) {
+  const { slug, lang } = await params;
+  const page = source.getPage(slug, lang);
+${isStrict ? `
+  if (!isAllowed(slug)) {
+    notFound();
+  }
+` : ""}
+  if (!page) {
+    notFound();
+  }
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc}>
+${pageActionsEnabled ? `      <div className="flex items-start justify-between gap-4">
+        <div>
+          <DocsTitle>{page.data.title}</DocsTitle>
+          {page.data.description && (
+            <DocsDescription>{page.data.description}</DocsDescription>
+          )}
+        </div>
+        <PageActions />
+      </div>` : `      <DocsTitle>{page.data.title}</DocsTitle>
+      {page.data.description && (
+        <DocsDescription>{page.data.description}</DocsDescription>
+      )}`}
+      <DocsBody data-content-area>
+        <MDX components={{ ...defaultMdxComponents, Steps, Step, Tabs, Tab, Files, File, Folder, Accordion, Accordions, TypeTable, Mermaid, Callout, CalloutTitle, CalloutDescription }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+${isStrict ? `
+export function generateStaticParams() {
+  let params = source.generateParams();
+  params = params.filter((p: { slug: string[]; lang: string }) => isAllowed(p.slug));
+  // Ensure every language has a homepage entry (slug: [])
+  const languages = [...new Set(params.map((p: { lang: string }) => p.lang))];
+  for (const lang of languages) {
+    if (!params.some((p: { slug: string[]; lang: string }) => p.slug.length === 0 && p.lang === lang)) {
+      const firstForLang = params.find((p: { slug: string[]; lang: string }) => p.lang === lang);
+      if (firstForLang) {
+        params.unshift({ ...firstForLang, slug: [] });
+      }
+    }
+  }
+  return params;
+}` : `
+export function generateStaticParams() {
+  const params = source.generateParams();
+  // Ensure every language has a homepage entry (slug: [])
+  const languages = [...new Set(params.map((p: { lang: string }) => p.lang))];
+  for (const lang of languages) {
+    if (!params.some((p: { slug: string[]; lang: string }) => p.slug.length === 0 && p.lang === lang)) {
+      const firstForLang = params.find((p: { slug: string[]; lang: string }) => p.lang === lang);
+      if (firstForLang) {
+        params.unshift({ ...firstForLang, slug: [] });
+      }
+    }
+  }
+  return params;
+}`}
+`;
+}
 
 //#endregion
 //#region src/core/generator/page-actions-component.ts
@@ -506,18 +721,246 @@ export default config;
 
 //#endregion
 //#region src/core/generator/provider.ts
+/**
+* 生成 app/provider.tsx（或 app/[lang]/provider.tsx）
+*
+* 重要：直接从 fumadocs-ui 导入组件，而非通过 openmanual/components/provider 中转。
+* 这避免了 pnpm file: 协议下 fumadocs-ui 被安装两次（一次作为 openmanual 的依赖，
+* 一次作为生成应用的依赖）导致的多实例 React Context 问题。
+*/
 function generateProvider(ctx) {
+	const searchEnabled = ctx.config.search?.enabled !== false;
+	if (ctx.config.i18n?.enabled === true) return `'use client';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import SafeSearchDialog from './components/search-dialog';
+import { i18nUI } from '@/lib/i18n-ui';
+import type { ReactNode } from 'react';
+
+export function AppProvider({ children, lang }: { children: ReactNode; lang: string }) {
+  return (
+    <RootProvider
+      i18n={i18nUI.provider(lang)}
+      search={{
+        enabled: ${searchEnabled},
+        SearchDialog: SafeSearchDialog,
+        options: { type: 'static', api: '/api/search' },
+      }}
+    >
+      {children}
+    </RootProvider>
+  );
+}
+`;
 	return `'use client';
-import { Provider } from 'openmanual/components/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import SafeSearchDialog from './components/search-dialog';
 import type { ReactNode } from 'react';
 
 export function AppProvider({ children }: { children: ReactNode }) {
   return (
-    <Provider
-      searchEnabled={${ctx.config.search?.enabled !== false}}
+    <RootProvider
+      search={{
+        enabled: ${searchEnabled},
+        SearchDialog: SafeSearchDialog,
+        options: { type: 'static', api: '/api/search' },
+      }}
     >
       {children}
-    </Provider>
+    </RootProvider>
+  );
+}
+`;
+}
+/**
+* 生成 app/components/search-dialog.tsx（或 app/[lang]/components/search-dialog.tsx）
+*
+* SafeSearchDialog 组件直接放在生成应用中，确保所有 fumadocs-ui 导入
+* 都来自同一个实例，避免 React Context 跨实例失效的问题。
+*
+* 重要修复：注入自定义 initOrama 解决 Orama 不支持中文等语言的问题。
+*
+* 问题根因：
+*   fumadocs-core 的 orama-static.js 在运行时调用 create({ language: 'zh' })，
+*   但 @orama/orama 不支持 'zh' 作为 language 参数（仅支持 31 种语言），
+*   会抛出 LANGUAGE_NOT_SUPPORTED 错误导致搜索功能完全失效。
+*
+* 修复方案：
+*   利用 fumadocs-core 的 StaticOptions.initOrama 扩展点，提供自定义的
+*   initOrama 函数。对于 Orama 不支持的语言（如 zh），不传 language 参数，
+*   让 Orama 使用默认的 english 分词器；对于支持的语言正常传入。
+*/
+function generateSearchDialog(_ctx) {
+	return `'use client';
+
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { useOnChange } from 'fumadocs-core/utils/use-on-change';
+import { create } from '@orama/orama';
+import {
+  SearchDialog,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogFooter,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  TagsList,
+  TagsListItem,
+} from 'fumadocs-ui/components/dialog/search';
+import { useI18n } from 'fumadocs-ui/contexts/i18n';
+import { useMemo, useState } from 'react';
+
+/**
+ * Orama 支持的语言名称集合。
+ *
+ * 不在此列表中的语言（如中文 zh）不能作为 language 参数传入 @orama/orama 的 create()，
+ * 否则会抛出 LANGUAGE_NOT_SUPPORTED 错误导致搜索功能完全失效。
+ *
+ * 来源：@orama/orama 内部的 SUPPORTED_LANGUAGES 列表，
+ * 与 fumadocs-core/dist/search/server.js 中的 STEMMERS 保持一致。
+ */
+const SUPPORTED_ORAMA_LANGUAGES = new Set([
+  'arabic', 'armenian', 'bulgarian', 'czech', 'danish', 'dutch',
+  'english', 'finnish', 'french', 'german', 'greek', 'hungarian',
+  'indian', 'indonesian', 'irish', 'italian', 'lithuanian', 'nepali',
+  'norwegian', 'portuguese', 'romanian', 'russian', 'serbian',
+  'slovenian', 'spanish', 'swedish', 'tamil', 'turkish',
+  'ukrainian', 'sanskrit',
+]);
+
+/**
+ * 将 locale code（如 'zh', 'en'）映射为 Orama 支持的 language 全名。
+ *
+ * 对于不支持的语言返回 undefined，此时 create() 不传 language 参数，
+ * Orama 会默认使用 english 分词器（对中文等语言做基本的空格/标点分词）。
+ */
+function resolveOramaLanguage(localeCode: string): string | undefined {
+  const map: Record<string, string> = {
+    ar: 'arabic', am: 'armenian', bg: 'bulgarian', cz: 'czech',
+    dk: 'danish', nl: 'dutch', en: 'english', fi: 'finnish',
+    fr: 'french', de: 'german', gr: 'greek', hu: 'hungarian',
+    in: 'indian', id: 'indonesian', ie: 'irish', it: 'italian',
+    lt: 'lithuanian', np: 'nepali', no: 'norwegian', pt: 'portuguese',
+    ro: 'romanian', ru: 'russian', rs: 'serbian', sl: 'slovenian',
+    es: 'spanish', se: 'swedish', ta: 'tamil', tr: 'turkish',
+    uk: 'ukrainian', sk: 'sanskrit',
+  };
+  const langName = map[localeCode];
+  return langName && SUPPORTED_ORAMA_LANGUAGES.has(langName) ? langName : undefined;
+}
+
+interface SafeSearchDialogProps {
+  defaultTag?: string;
+  tags?: { value: string; name: string }[];
+  api?: string;
+  delayMs?: number;
+  type?: 'fetch' | 'static';
+  allowClear?: boolean;
+  links?: [string, string][];
+  footer?: React.ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export default function SafeSearchDialog({
+  defaultTag,
+  tags = [],
+  api,
+  delayMs,
+  type = 'fetch',
+  allowClear = false,
+  links = [],
+  footer,
+  open = false,
+  onOpenChange = (): void => {},
+}: SafeSearchDialogProps) {
+  const { locale } = useI18n();
+  const [tag, setTag] = useState(defaultTag);
+
+  /**
+   * 自定义 initOrama：根据 locale 是否受 Orama 支持，决定是否传入 language 参数。
+   *
+   * 这解决了 Orama 不支持 'zh' 等语言时抛出 LANGUAGE_NOT_SUPPORTED 导致搜索失效的问题。
+   * fumadocs-core 的 StaticOptions 类型已官方暴露 initOrama 参数供此用途。
+   */
+  const safeInitOrama = useMemo(
+    () => (localeCode?: string) => {
+      const lang = localeCode ? resolveOramaLanguage(localeCode) : undefined;
+      return create({
+        schema: { _: 'string' },
+        ...(lang ? { language: lang } : {}),
+      });
+    },
+    [],
+  );
+
+  const { search, setSearch, query } = useDocsSearch(
+    type === 'fetch'
+      ? {
+          type: 'fetch',
+          ...(api != null && { api }),
+          ...(locale != null && { locale }),
+          ...(tag != null && { tag }),
+          ...(delayMs != null && { delayMs }),
+        }
+      : {
+          type: 'static',
+          ...(api != null && { from: api }),
+          ...(locale != null && { locale }),
+          ...(tag != null && { tag }),
+          ...(delayMs != null && { delayMs }),
+          initOrama: safeInitOrama,
+        }
+  );
+
+  const defaultItems = useMemo(() => {
+    if (links.length === 0) return null;
+    return links.map(([name, link]) => ({
+      type: 'page' as const,
+      id: name,
+      content: name,
+      url: link,
+    }));
+  }, [links]);
+
+  useOnChange(defaultTag, (v) => {
+    setTag(v);
+  });
+
+  // 核心修复：使用 Array.isArray 守卫，防止非数组值导致 .map() 报错
+  const safeItems = Array.isArray(query.data) ? query.data : defaultItems;
+
+  return (
+    <SearchDialog
+      open={open}
+      onOpenChange={onOpenChange}
+      search={search}
+      onSearchChange={setSearch}
+      isLoading={query.isLoading}
+    >
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        <SearchDialogList items={safeItems} />
+      </SearchDialogContent>
+      <SearchDialogFooter>
+        {tags.length > 0 && (
+          <TagsList {...(tag != null && { tag })} onTagChange={setTag} allowClear={allowClear}>
+            {tags.map((tagItem) => (
+              <TagsListItem key={tagItem.value} value={tagItem.value}>
+                {tagItem.name}
+              </TagsListItem>
+            ))}
+          </TagsList>
+        )}
+        {footer}
+      </SearchDialogFooter>
+    </SearchDialog>
   );
 }
 `;
@@ -525,7 +968,83 @@ export function AppProvider({ children }: { children: ReactNode }) {
 
 //#endregion
 //#region src/core/generator/raw-content-route.ts
-function generateRawContentRoute() {
+function generateRawContentRoute(ctx) {
+	const isI18n = ctx.config.i18n?.enabled === true;
+	const useDirParser = isDirParser(ctx.config);
+	if (isI18n && useDirParser) return `import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { NextResponse } from 'next/server';
+
+const _defaultLang = '${ctx.config.i18n?.defaultLanguage ?? ctx.config.locale ?? "zh"}';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  const { path: segments } = await params;
+  const slug = segments.join('/');
+  // 从查询参数获取语言，回退到默认语言（API 路由不在 [lang] 路径段下）
+  const { searchParams } = new URL(request.url);
+  const lang = searchParams.get('lang') ?? _defaultLang;
+  // dir parser: 文件位于 content/{lang}/{slug}.ext
+  for (const ext of ['.mdx', '.md']) {
+    try {
+      const filePath = join(process.cwd(), 'content', lang, \`\${slug}\${ext}\`);
+      const content = await readFile(filePath, 'utf-8');
+      return new NextResponse(content, {
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      });
+    } catch {
+      /* try next extension */
+    }
+  }
+  return new NextResponse('Not found', { status: 404 });
+}
+`;
+	if (isI18n) return `import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { NextResponse } from 'next/server';
+
+const _defaultLang = '${ctx.config.i18n?.defaultLanguage ?? ctx.config.locale ?? "zh"}';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  const { path: segments } = await params;
+  const slug = segments.join('/');
+  // 从查询参数获取语言，回退到默认语言（API 路由不在 [lang] 路径段下）
+  const { searchParams } = new URL(request.url);
+  const lang = searchParams.get('lang') ?? _defaultLang;
+  // 尝试带语言后缀的文件，再回退到默认语言文件
+  const suffix = lang !== _defaultLang ? \`.\${lang}\` : '';
+  for (const ext of ['.mdx', '.md']) {
+    // 先尝试带后缀
+    if (suffix) {
+      try {
+        const filePath = join(process.cwd(), 'content', \`\${slug}\${suffix}\${ext}\`);
+        const content = await readFile(filePath, 'utf-8');
+        return new NextResponse(content, {
+          headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+        });
+      } catch {
+        /* 回退 */
+      }
+    }
+    // 再尝试不带后缀（默认语言或 fallback）
+    try {
+      const filePath = join(process.cwd(), 'content', \`\${slug}\${ext}\`);
+      const content = await readFile(filePath, 'utf-8');
+      return new NextResponse(content, {
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      });
+    } catch {
+      /* try next extension */
+    }
+  }
+  return new NextResponse('Not found', { status: 404 });
+}
+`;
 	return `import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { NextResponse } from 'next/server';
@@ -554,7 +1073,71 @@ export async function GET(
 
 //#endregion
 //#region src/core/generator/search-route.ts
-function generateSearchRoute() {
+/**
+* Orama/FlexSearch 支持的语言映射（来自 fumadocs-core/dist/search/server.js STEMMERS）
+*
+* key = 语言全名（传给 tokenizer 的 language 值），value = 语言代码（locale code）
+*
+* 不在此列表中的语言（如中文 zh）不能作为 language 参数传入，
+* 否则构建时会抛出 "Language X is not supported" 错误。
+* 对于不支持的语言，传入空对象 {} 让 Orama 使用默认分词器。
+*/
+const SUPPORTED_LOCALE_MAP = {
+	arabic: "ar",
+	armenian: "am",
+	bulgarian: "bg",
+	czech: "cz",
+	danish: "dk",
+	dutch: "nl",
+	english: "en",
+	finnish: "fi",
+	french: "fr",
+	german: "de",
+	greek: "gr",
+	hungarian: "hu",
+	indian: "in",
+	indonesian: "id",
+	irish: "ie",
+	italian: "it",
+	lithuanian: "lt",
+	nepali: "np",
+	norwegian: "no",
+	portuguese: "pt",
+	romanian: "ro",
+	russian: "ru",
+	serbian: "rs",
+	slovenian: "ru",
+	spanish: "es",
+	swedish: "se",
+	tamil: "ta",
+	turkish: "tr",
+	ukrainian: "uk",
+	sanskrit: "sk"
+};
+/**
+* 根据语言代码查找对应的支持的 language 名称
+* 例如：'en' → 'english'，'zh' → undefined（不支持）
+*/
+function resolveLanguageName(localeCode) {
+	return Object.keys(SUPPORTED_LOCALE_MAP).find((key) => SUPPORTED_LOCALE_MAP[key] === localeCode);
+}
+function generateSearchRoute(ctx) {
+	const i18nCfg = ctx?.config.i18n;
+	if (i18nCfg?.enabled === true && i18nCfg.languages && i18nCfg.languages.length >= 2) return `import { source } from '@/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const revalidate = false;
+const _localeMap: Record<string, unknown> = {
+${(i18nCfg?.languages ?? []).map((l) => {
+		const langName = resolveLanguageName(l.code);
+		if (langName) return `  ${l.code}: '${langName}'`;
+		return `  ${l.code}: {}`;
+	}).join(",\n")},
+};
+export const { staticGET: GET } = createFromSource(source, {
+  localeMap: _localeMap as any,
+});
+`;
 	return `import { source } from '@/lib/source';
 import { createFromSource } from 'fumadocs-core/search/server';
 
@@ -570,6 +1153,8 @@ function generateSourceConfig(_ctx) {
 	const titleMapEntries = Object.entries(titleMap).map(([slug, title]) => `  '${slug}': '${title.replace(/'/g, "\\'")}'`).join(",\n");
 	const titleMapStr = titleMapEntries ? `{\n${titleMapEntries}\n}` : "{}";
 	const isStrict = _ctx.config.contentPolicy !== "all";
+	const isI18n = isI18nEnabled(_ctx.config);
+	const useDirParser = isDirParser(_ctx.config);
 	return `import { defineDocs, defineConfig } from 'fumadocs-mdx/config';
 import { remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
 import { z } from 'zod';
@@ -581,16 +1166,36 @@ const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.co
 function slugFromPath(path: string): string {
   const normalized = path.replace(/\\\\/g, '/');
   const idx = normalized.indexOf('content/');
-  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;
-  return relative.replace(/\\.(md|mdx)$/i, '');
-}
-` : ""}
+  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;${useDirParser ? `
+  // dir parser: 剥离语言目录前缀 content/en/guide/configuration.mdx -> guide/configuration
+  const parts = relative.split('/');
+  if (parts.length > 1 && /^[a-z]{2}(-[A-Z]{2})?$/i.test(parts[0])) {
+    return parts.slice(1).join('/').replace(/\\.(md|mdx)$/i, '');
+  }
+  return relative.replace(/\\.(md|mdx)$/i, '');` : `
+  let slug = relative.replace(/\\.(md|mdx)$/i, '');
+${isI18n ? `  // 剥离语言后缀：index.en -> index
+  slug = slug.replace(/\\.([a-z]{2}(-[A-Z]{2})?)$/, '');` : ""}
+  return slug;`}
+}` : ""}
 function titleFromPath(path: string): string {
-  const normalized = path.replace(/\\\\/g, '/');
+${useDirParser ? `  const normalized = path.replace(/\\\\/g, '/');
   const idx = normalized.indexOf('content/');
   const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;
+  // dir parser: 剥离语言目录前缀 content/en/guide/configuration.mdx -> guide/configuration
+  const parts = relative.split('/');
+  if (parts.length > 1 && /^[a-z]{2}(-[A-Z]{2})?$/i.test(parts[0])) {
+    const slug = parts.slice(1).join('/').replace(/\\.(md|mdx)$/i, '');
+    return titleMap[slug] || slug.split('/').pop() || slug;
+  }
   const slug = relative.replace(/\\.(md|mdx)$/i, '');
-  return titleMap[slug] || slug.split('/').pop() || slug;
+  return titleMap[slug] || slug.split('/').pop() || slug;` : `  const normalized = path.replace(/\\\\/g, '/');
+  const idx = normalized.indexOf('content/');
+  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;
+  let slug = relative.replace(/\\.(md|mdx)$/i, '');
+${isI18n ? `  // 剥离语言后缀：guide/configuration.en -> guide/configuration
+  slug = slug.replace(/\\.([a-z]{2}(-[A-Z]{2})?)$/, '');` : ""}
+  return titleMap[slug] || slug.split('/').pop() || slug;`}
 }
 
 export const docs = defineDocs({
@@ -671,7 +1276,8 @@ function generateTsconfig() {
 //#endregion
 //#region src/core/generator/index.ts
 async function generateAll(ctx) {
-	const files = [
+	const isI18n = isI18nEnabled(ctx.config);
+	const baseFiles = [
 		{
 			path: "source.config.ts",
 			content: generateSourceConfig(ctx)
@@ -698,7 +1304,7 @@ async function generateAll(ctx) {
 		},
 		{
 			path: "lib/source.ts",
-			content: generateLibSource()
+			content: generateLibSource(ctx)
 		},
 		{
 			path: "lib/layout.tsx",
@@ -715,16 +1321,65 @@ async function generateAll(ctx) {
 		{
 			path: "components/page-actions.tsx",
 			content: generatePageActionsComponent()
+		}
+	];
+	let files;
+	if (isI18n) files = [
+		...baseFiles,
+		{
+			path: "lib/i18n.ts",
+			content: generateI18nConfig(ctx)
+		},
+		{
+			path: "lib/i18n-ui.ts",
+			content: generateI18nUI(ctx)
+		},
+		{
+			path: "middleware.ts",
+			content: generateMiddleware(ctx)
+		},
+		...ctx.dev ? [{
+			path: "app/api/raw/[...path]/route.ts",
+			content: generateRawContentRoute(ctx)
+		}, {
+			path: "app/api/search/route.ts",
+			content: generateSearchRoute(ctx)
+		}] : [{
+			path: "app/api/search/route.ts",
+			content: generateSearchRoute(ctx)
+		}],
+		{
+			path: "app/[lang]/layout.tsx",
+			content: generateRootLayoutI18n(ctx)
+		},
+		{
+			path: "app/[lang]/provider.tsx",
+			content: generateProvider(ctx)
+		},
+		{
+			path: "app/[lang]/components/search-dialog.tsx",
+			content: generateSearchDialog(ctx)
 		},
+		{
+			path: "app/[lang]/[[...slug]]/layout.tsx",
+			content: generateDocsLayout(ctx)
+		},
+		{
+			path: "app/[lang]/[[...slug]]/page.tsx",
+			content: generatePage(ctx)
+		}
+	];
+	else files = [
+		...baseFiles,
 		...ctx.dev ? [{
 			path: "app/api/raw/[...path]/route.ts",
-			content: generateRawContentRoute()
+			content: generateRawContentRoute(ctx)
 		}, {
 			path: "app/api/search/route.ts",
-			content: generateSearchRoute()
+			content: generateSearchRoute(ctx)
 		}] : [{
 			path: "app/api/search/route.ts",
-			content: generateSearchRoute()
+			content: generateSearchRoute(ctx)
 		}],
 		{
 			path: "app/layout.tsx",
@@ -734,6 +1389,10 @@ async function generateAll(ctx) {
 			path: "app/provider.tsx",
 			content: generateProvider(ctx)
 		},
+		{
+			path: "app/components/search-dialog.tsx",
+			content: generateSearchDialog(ctx)
+		},
 		{
 			path: "app/[[...slug]]/layout.tsx",
 			content: generateDocsLayout(ctx)
@@ -782,11 +1441,53 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 }
 `;
 }
+/**
+* 生成 app/[lang]/layout.tsx — 多语言模式的根布局
+*
+* 与单语言模式的关键区别：
+* 1. 从 params 中获取 lang 参数
+* 2. AppLayout 接收 lang 参数设置 html lang 属性
+* 3. AppProvider 接收 lang 参数用于 i18n UI
+*/
+function generateRootLayoutI18n(ctx) {
+	const { config } = ctx;
+	const favicon = config.favicon;
+	return `${favicon ? `import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  icons: {
+    icon: '${favicon}',
+  },
+};
+
+` : ""}import { AppLayout } from 'openmanual/components/app-layout';
+import { AppProvider } from './provider';
+import type { ReactNode } from 'react';
+import '../../global.css';
+
+export default async function RootLayout({
+  params,
+  children,
+}: {
+  params: Promise<{ lang: string }>;
+  children: ReactNode;
+}) {
+  const { lang } = await params;
+
+  return (
+    <AppLayout lang={lang}>
+      <AppProvider lang={lang}>{children}</AppProvider>
+    </AppLayout>
+  );
+}
+`;
+}
 function generateDocsLayout(ctx) {
 	const { config } = ctx;
 	const githubLink = config.navbar?.github ?? "";
 	const navLinks = config.navbar?.links ?? [];
 	const footerText = config.footer?.text ?? "";
+	const isI18n = isI18nEnabled(config);
 	const linksArray = navLinks.map((l) => ({
 		text: l.label,
 		url: l.href,
@@ -817,14 +1518,43 @@ function generateDocsLayout(ctx) {
 	const lucideImportLine = hasIcons ? `\nimport { ${iconNameList.join(", ")} } from 'lucide-react';` : "";
 	const iconMapSnippet = hasIcons ? `\nconst iconMap = {${iconNameList.map((name) => `\n  ${name}: <${name} />,`).join("")}\n} as const;
 ` : "";
+	const treeLine = hasSidebar ? hasIcons ? isI18n ? "tree: restructureTree(source.getPageTree(lang), sidebarConfig, iconMap)," : "tree: restructureTree(source.getPageTree(), sidebarConfig, iconMap)," : isI18n ? "tree: restructureTree(source.getPageTree(lang), sidebarConfig)," : "tree: restructureTree(source.getPageTree(), sidebarConfig)," : isI18n ? "tree: source.getPageTree(lang)," : "tree: source.getPageTree(),";
+	const restructureTreeImport = hasSidebar ? "\nimport { restructureTree } from 'openmanual/utils/restructure-tree';" : "";
+	if (isI18n) return `import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { baseOptions } from '@/lib/layout';
+import { source } from '@/lib/source';
+import type { ReactNode } from 'react';${restructureTreeImport}${lucideImportLine}
+${sidebarConfigSnippet}${iconMapSnippet}
+
+export default async function DocsLayoutWrapper({
+  params,
+  children,
+}: {
+  params: Promise<{ lang: string }>;
+  children: ReactNode;
+}) {
+  const { lang } = await params;
+
+  const docsOptions = {
+    ...baseOptions(lang),
+    ${treeLine}${githubLine}${linksLine}${footerLine}
+  };
+
+  return (
+    <DocsLayout {...docsOptions}>
+      {children}
+    </DocsLayout>
+  );
+}
+`;
 	return `import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 import { baseOptions } from '@/lib/layout';
 import { source } from '@/lib/source';
-import type { ReactNode } from 'react';${hasSidebar ? "\nimport { restructureTree } from 'openmanual/utils/restructure-tree';" : ""}${lucideImportLine}
+import type { ReactNode } from 'react';${restructureTreeImport}${lucideImportLine}
 ${sidebarConfigSnippet}${iconMapSnippet}
 const docsOptions = {
   ...baseOptions(),
-  ${hasSidebar ? hasIcons ? "tree: restructureTree(source.getPageTree(), sidebarConfig, iconMap)," : "tree: restructureTree(source.getPageTree(), sidebarConfig)," : "tree: source.getPageTree(),"}${githubLine}${linksLine}${footerLine}
+  ${treeLine}${githubLine}${linksLine}${footerLine}
 };
 
 export default function DocsLayoutWrapper({ children }: { children: ReactNode }) {
@@ -858,14 +1588,14 @@ async function ensureLogoFile(ctx, logoPath, variant) {
 	}
 }
 /**
-* Generate meta.json for each sidebar group directory so that
-* fumadocs displays the configured Chinese group name instead of
-* auto-capitalizing the English directory name.
+* Generate meta.json (and meta.en.json in i18n mode) for each sidebar
+* group directory so that fumadocs displays the configured group name.
 */
 async function generateMetaFiles(ctx) {
 	const sidebar = ctx.config.sidebar;
 	if (!sidebar || sidebar.length === 0) return;
 	const contentAbsDir = join(ctx.projectDir, ctx.contentDir);
+	const isI18n = isI18nEnabled(ctx.config);
 	for (const group of sidebar) {
 		const dirPrefix = group.pages.map((p) => p.slug).find((slug) => slug.includes("/"))?.split("/")[0];
 		if (!dirPrefix) continue;
@@ -873,30 +1603,17 @@ async function generateMetaFiles(ctx) {
 		const metaPath = join(dirPath, "meta.json");
 		try {
 			await access(metaPath);
-			continue;
-		} catch {}
-		await mkdir(dirPath, { recursive: true });
-		await writeFile(metaPath, `${JSON.stringify({ title: group.group }, null, 2)}\n`, "utf-8");
-	}
-}
-
-//#endregion
-//#region src/utils/copy-raw-markdown.ts
-/**
-* Recursively copy .mdx/.md files from contentDir to targetDir,
-* renaming extensions to .md. Non-markdown files are skipped.
-*/
-async function copyRawMarkdown(contentDir, targetDir) {
-	await mkdir(targetDir, { recursive: true });
-	const entries = await readdir(contentDir);
-	for (const entry of entries) {
-		const srcPath = join(contentDir, entry);
-		if ((await stat(srcPath)).isDirectory()) await copyRawMarkdown(srcPath, join(targetDir, entry));
-		else {
-			const ext = parse(entry).ext.toLowerCase();
-			if (ext === ".mdx" || ext === ".md") {
-				const { name } = parse(entry);
-				await copyFile(srcPath, join(targetDir, `${name}.md`));
+		} catch {
+			await mkdir(dirPath, { recursive: true });
+			await writeFile(metaPath, `${JSON.stringify({ title: group.group }, null, 2)}\n`, "utf-8");
+		}
+		if (isI18n) {
+			const metaEnPath = join(dirPath, "meta.en.json");
+			try {
+				await access(metaEnPath);
+			} catch {
+				await mkdir(dirPath, { recursive: true });
+				await writeFile(metaEnPath, `${JSON.stringify({ title: group.group }, null, 2)}\n`, "utf-8");
 			}
 		}
 	}
@@ -962,7 +1679,7 @@ const logger = {
 
 //#endregion
 //#region src/utils/temp-dir.ts
-const TEMP_DIR_NAME = ".openmanual";
+const TEMP_DIR_NAME = ".cache";
 function getTempDir(cwd) {
 	return join(cwd, TEMP_DIR_NAME);
 }
@@ -972,6 +1689,7 @@ function getAppDir(cwd) {
 async function ensureTempDir(cwd) {
 	const tempDir = getTempDir(cwd);
 	const appDir = getAppDir(cwd);
+	await cleanTempDir(cwd);
 	await mkdir(tempDir, { recursive: true });
 	await mkdir(join(appDir, "app"), { recursive: true });
 	return tempDir;
@@ -1046,8 +1764,21 @@ const buildCommand = new Command("build").description("构建静态站点").acti
 		} catch {
 			logger.warn("未找到静态导出产物，请检查 next.config.mjs 中 output: \"export\" 配置");
 		}
-		logger.step("复制原始 Markdown 文件...");
-		await copyRawMarkdown(contentDir, outputDir);
+		if (config.i18n?.enabled) {
+			const defaultLang = config.i18n.defaultLanguage ?? config.locale ?? "zh";
+			const redirectHtml = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta http-equiv="refresh" content="0;url=/${defaultLang}" />
+  <script>window.location.href='/${defaultLang}';<\/script>
+</head>
+<body>
+  <p>Redirecting to <a href="/${defaultLang}">/${defaultLang}</a>...</p>
+</body>
+</html>`;
+			await writeFile(resolve(outputDir, "index.html"), redirectHtml, "utf-8");
+		}
 		logger.step("清理临时文件...");
 		await cleanTempDir(cwd);
 		logger.success("构建完成！");
@@ -1341,7 +2072,7 @@ const regenerateCommand = new Command("_regenerate").description("内部命令
 //#endregion
 //#region src/cli/bin.ts
 function getVersion() {
-	return "0.10.0";
+	return "0.11.0";
 }
 const program = new Command();
 const commandName = basename(process.argv[1] ?? "openmanual");