Refactor i18n, translation, and MDX config for multi-language support

Reworks translation file handling in the CLI to use a dot-suffix convention and dynamic language configuration from docs.site.json. Adds a translations utility for UI strings, updates layouts to use dynamic translations, and improves the root proxy to redirect based on Accept-Language. Adds remark-directive and admonition plugins to MDX config for enhanced markdown support. Cleans up MDX component injection and updates dependencies accordingly.

Author: hotlong

package.json

@@ -18,8 +18,6 @@
     "fumadocs-core": "16.4.7",
     "fumadocs-mdx": "14.2.5",
     "fumadocs-ui": "16.4.7",
-    "lucide-react": "^0.562.0",
-    "next": "16.1.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "server-only": "^0.0.1",

packages/cli/README.md

@@ -39,7 +39,7 @@ pnpm objectdocs build ./content/docs
 
 ### Translate Documentation
 
-The `translate` command reads English documentation from `content/docs` and generates Chinese translations in `content/docs-cn`.
+The `translate` command reads English documentation from `content/docs/*.mdx` and generates Chinese translations as `*.cn.mdx` files in the same directory using the dot parser convention.
 
 **Prerequisites:**
 You must set the following environment variables (in `.env` or your shell):

packages/cli/src/commands/translate.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import OpenAI from 'openai';
-import { getAllMdxFiles, resolveTranslatedFilePath, translateContent } from '../utils/translate.mjs';
+import { getAllMdxFiles, resolveTranslatedFilePath, translateContent, getSiteConfig } from '../utils/translate.mjs';
 
 export function registerTranslateCommand(cli) {
   cli
@@ -22,6 +22,11 @@ export function registerTranslateCommand(cli) {
         baseURL: OPENAI_BASE_URL,
       });
 
+      // Get language configuration
+      const config = getSiteConfig();
+      console.log(`Translation target: ${config.defaultLanguage} -> ${config.targetLanguage}`);
+      console.log(`Configured languages: ${config.languages.join(', ')}\n`);
+
       let targetFiles = [];
 
       if (options.all) {

packages/cli/src/utils/translate.mjs

@@ -2,6 +2,70 @@ import fs from 'node:fs';
 import path from 'node:path';
 import OpenAI from 'openai';
 
+/**
+ * Load site configuration from docs.site.json
+ * @returns {object} - The site configuration
+ */
+function loadSiteConfig() {
+  const configPath = path.resolve(process.cwd(), 'content/docs.site.json');
+  
+  if (!fs.existsSync(configPath)) {
+    console.warn(`Warning: docs.site.json not found at ${configPath}, using defaults`);
+    // Fallback matches the default configuration in packages/site/lib/site-config.ts
+    return {
+      i18n: {
+        enabled: true,
+        defaultLanguage: 'en',
+        languages: ['en', 'cn']
+      }
+    };
+  }
+  
+  try {
+    const configContent = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(configContent);
+  } catch (error) {
+    console.error('Error loading docs.site.json:', error);
+    throw error;
+  }
+}
+
+// Load configuration
+const siteConfig = loadSiteConfig();
+const languages = siteConfig.i18n?.languages || ['en', 'cn'];
+const defaultLanguage = siteConfig.i18n?.defaultLanguage || 'en';
+
+// Generate language suffixes dynamically from config
+// e.g., ['en', 'cn'] -> ['.en.mdx', '.cn.mdx']
+const LANGUAGE_SUFFIXES = languages.map(lang => `.${lang}.mdx`);
+
+// Target language is the first non-default language
+const targetLanguage = languages.find(lang => lang !== defaultLanguage) || languages[0];
+const TARGET_LANGUAGE_SUFFIX = `.${targetLanguage}.mdx`;
+
+/**
+ * Get the current site configuration
+ * @returns {object} - Configuration object with languages info
+ */
+export function getSiteConfig() {
+  return {
+    languages,
+    defaultLanguage,
+    targetLanguage,
+    languageSuffixes: LANGUAGE_SUFFIXES,
+    targetLanguageSuffix: TARGET_LANGUAGE_SUFFIX,
+  };
+}
+
+/**
+ * Check if a file has a language suffix
+ * @param {string} filePath - The file path to check
+ * @returns {boolean} - True if file has a language suffix
+ */
+function hasLanguageSuffix(filePath) {
+  return LANGUAGE_SUFFIXES.some(suffix => filePath.endsWith(suffix));
+}
+
 export function getAllMdxFiles(dir) {
   let results = [];
   if (!fs.existsSync(dir)) return results;
@@ -13,7 +77,8 @@ export function getAllMdxFiles(dir) {
     if (stat && stat.isDirectory()) {
       results = results.concat(getAllMdxFiles(file));
     } else {
-      if (file.endsWith('.mdx')) {
+      // Only include .mdx files that don't have language suffix
+      if (file.endsWith('.mdx') && !hasLanguageSuffix(file)) {
         results.push(path.relative(process.cwd(), file));
       }
     }
@@ -22,19 +87,23 @@ export function getAllMdxFiles(dir) {
 }
 
 export function resolveTranslatedFilePath(enFilePath) {
-  // Strategy: content/docs/path/to/file.mdx -> content/docs-cn/path/to/file.mdx
-  const docsRoot = path.join(process.cwd(), 'content/docs');
-  
-  // If input path is relative, make it absolute first to check
+  // Strategy: Use dot parser convention
+  // content/docs/path/to/file.mdx -> content/docs/path/to/file.{targetLang}.mdx
+  // Target language is determined from docs.site.json configuration
+  // Skip files that already have language suffix
   const absPath = path.resolve(enFilePath);
 
-  if (!absPath.startsWith(docsRoot)) {
-     // Fallback or specific logic if file is not in content/docs
-     return enFilePath.replace('content/docs', 'content/docs-cn');
+  // Skip if already has a language suffix
+  if (hasLanguageSuffix(absPath)) {
+    return absPath;
   }
-
-  const relativePath = path.relative(docsRoot, enFilePath);
-  return path.join(process.cwd(), 'content/docs-cn', relativePath);
+  
+  // Replace .mdx with target language suffix
+  if (absPath.endsWith('.mdx')) {
+    return absPath.replace(/\.mdx$/, TARGET_LANGUAGE_SUFFIX);
+  }
+  
+  return absPath;
 }
 
 export async function translateContent(content, openai, model) {

packages/site/app/[lang]/docs/[[...slug]]/page.tsx

@@ -4,9 +4,18 @@ import { DocsPage, DocsBody } from 'fumadocs-ui/page';
 import { notFound } from 'next/navigation';
 import { siteConfig } from '@/lib/site-config';
 import defaultComponents from 'fumadocs-ui/mdx';
-import { Steps, Step } from 'fumadocs-ui/components/steps';
-import { Card, Cards } from 'fumadocs-ui/components/card';
 import { Callout } from 'fumadocs-ui/components/callout';
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { Steps, Step } from 'fumadocs-ui/components/steps';
+
+const components = {
+  ...defaultComponents,
+  Callout,
+  Card,
+  Cards,
+  Steps,
+  Step,
+};
 
 interface PageProps {
   params: Promise<{
@@ -43,7 +52,7 @@ export default async function Page({ params }: PageProps) {
       } : undefined}
     >
       <DocsBody>
-        <MDX components={{ ...defaultComponents, Steps, Step, Card, Cards, Callout }} />
+        <MDX components={components} />
       </DocsBody>
     </DocsPage>
   );

packages/site/app/[lang]/layout.tsx

@@ -2,24 +2,11 @@ import 'fumadocs-ui/style.css';
 import { RootProvider } from 'fumadocs-ui/provider/next';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';
+import { getTranslations } from '@/lib/translations';
 
 
 const { provider } = defineI18nUI(i18n, {
-  translations: {
-    en: {
-      displayName: 'English',
-    },
-    cn: {
-      displayName: '简体中文',
-      toc: '目录',
-      search: '搜索文档',
-      lastUpdate: '最后更新于',
-      searchNoResult: '没有结果',
-      previousPage: '上一页',
-      nextPage: '下一页',
-      chooseLanguage: '选择语言',
-    },
-  },
+  translations: getTranslations(),
 });
 
 export default async function Layout({ params, children }: LayoutProps<'/[lang]'>) {

packages/site/app/layout.tsx

@@ -2,17 +2,11 @@ import 'fumadocs-ui/style.css';
 import { RootProvider } from 'fumadocs-ui/provider/next';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';
+import { getTranslations } from '@/lib/translations';
 
 
 const { provider } = defineI18nUI(i18n, {
-  translations: {
-    en: {
-      displayName: 'English',
-    },
-    cn: {
-      displayName: 'Chinese', 
-    },
-  },
+  translations: getTranslations(),
 });
 
 export default function Layout({ children }: { children: React.ReactNode }) {

packages/site/app/page.tsx

@@ -0,0 +1,11 @@
+import { redirect } from 'next/navigation';
+
+/**
+ * Root page - redirects are handled by proxy.ts middleware
+ * This page should never actually render as the middleware intercepts and redirects
+ * But Next.js requires a page component for the route to be recognized
+ */
+export default function RootPage() {
+  // Fallback redirect if middleware didn't handle it
+  redirect('/en/docs');
+}

packages/site/lib/translations.ts

@@ -0,0 +1,102 @@
+import { siteConfig } from './site-config';
+
+/**
+ * Translation strings for different languages
+ * These are the UI strings used by fumadocs-ui
+ */
+interface LanguageTranslations {
+  displayName: string;
+  toc?: string;
+  search?: string;
+  lastUpdate?: string;
+  searchNoResult?: string;
+  previousPage?: string;
+  nextPage?: string;
+  chooseLanguage?: string;
+}
+
+/**
+ * Default translations for supported languages
+ * Add new language translations here as needed
+ */
+const defaultTranslations: Record<string, LanguageTranslations> = {
+  en: {
+    displayName: 'English',
+  },
+  cn: {
+    displayName: '简体中文',
+    toc: '目录',
+    search: '搜索文档',
+    lastUpdate: '最后更新于',
+    searchNoResult: '没有结果',
+    previousPage: '上一页',
+    nextPage: '下一页',
+    chooseLanguage: '选择语言',
+  },
+  ja: {
+    displayName: '日本語',
+    toc: '目次',
+    search: 'ドキュメントを検索',
+    lastUpdate: '最終更新',
+    searchNoResult: '結果がありません',
+    previousPage: '前のページ',
+    nextPage: '次のページ',
+    chooseLanguage: '言語を選択',
+  },
+  fr: {
+    displayName: 'Français',
+    toc: 'Table des matières',
+    search: 'Rechercher dans la documentation',
+    lastUpdate: 'Dernière mise à jour',
+    searchNoResult: 'Aucun résultat',
+    previousPage: 'Page précédente',
+    nextPage: 'Page suivante',
+    chooseLanguage: 'Choisir la langue',
+  },
+  de: {
+    displayName: 'Deutsch',
+    toc: 'Inhaltsverzeichnis',
+    search: 'Dokumentation durchsuchen',
+    lastUpdate: 'Zuletzt aktualisiert',
+    searchNoResult: 'Keine Ergebnisse',
+    previousPage: 'Vorherige Seite',
+    nextPage: 'Nächste Seite',
+    chooseLanguage: 'Sprache wählen',
+  },
+  es: {
+    displayName: 'Español',
+    toc: 'Tabla de contenidos',
+    search: 'Buscar documentación',
+    lastUpdate: 'Última actualización',
+    searchNoResult: 'Sin resultados',
+    previousPage: 'Página anterior',
+    nextPage: 'Página siguiente',
+    chooseLanguage: 'Elegir idioma',
+  },
+};
+
+/**
+ * Get translations for configured languages
+ * Returns only the translations for languages specified in docs.site.json
+ */
+export function getTranslations(): Record<string, LanguageTranslations> {
+  const configuredLanguages = siteConfig.i18n.languages;
+  const translations: Record<string, LanguageTranslations> = {};
+
+  for (const lang of configuredLanguages) {
+    if (defaultTranslations[lang]) {
+      translations[lang] = defaultTranslations[lang];
+    } else {
+      // If no translation exists for a configured language, provide a minimal fallback
+      // Only log warning in development
+      if (process.env.NODE_ENV === 'development') {
+        console.warn(`Warning: No translations found for language "${lang}". Using minimal fallback.`);
+      }
+      translations[lang] = {
+        displayName: lang.toUpperCase(),
+      };
+    }
+  }
+
+  return translations;
+}

packages/site/mdx-components.tsx

@@ -1,17 +1,12 @@
 import defaultComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
 import { Steps, Step } from 'fumadocs-ui/components/steps';
-import { Card, Cards } from 'fumadocs-ui/components/card';
-import { Callout } from 'fumadocs-ui/components/callout';
 
 export function useMDXComponents(components: MDXComponents): MDXComponents {
   return {
     ...defaultComponents,
     Steps,
     Step,
-    Card,
-    Cards,
-    Callout,
     ...components,
   };
 }