docs-i18n 0.8.2 → 0.8.4

package/admin/dist/server/server.js

@@ -15572,10 +15572,6 @@ var manifest = {
 		functionName: "openFile_createServerFn_handler",
 		importer: () => import("./assets/misc-y6t3-UOP.js")
 	},
-	"5080dc3f2f2309ec6981b94c431969637130c657e8a1dfb10400b4614eecc1ea": {
-		functionName: "fetchModels_createServerFn_handler",
-		importer: () => import("./assets/models-YNa3F3nn.js")
-	},
 	"4e218d79545765572808c7eab33b7663d4496209c15406d0b449366905b6b83f": {
 		functionName: "fetchStatus_createServerFn_handler",
 		importer: () => import("./assets/status-CM7Azp4n.js")
@@ -15611,6 +15607,10 @@ var manifest = {
 	"88c2855c84e91504070bfecc50ddfa50339d22c305626800b6d9b05d79385d71": {
 		functionName: "deleteJob_createServerFn_handler",
 		importer: () => import("./assets/jobs-FXffC7LH.js")
+	},
+	"5080dc3f2f2309ec6981b94c431969637130c657e8a1dfb10400b4614eecc1ea": {
+		functionName: "fetchModels_createServerFn_handler",
+		importer: () => import("./assets/models-YNa3F3nn.js")
 	}
 };
 async function getServerFnById(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-i18n",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Universal documentation translation engine — parse, translate, cache, assemble, manage.",
   "type": "module",
   "bin": {

package/template/app/components/BlogArticle.tsx

@@ -19,7 +19,7 @@ import { MarkdownContent } from '~/components/markdown'
 import { Toc } from '~/components/Toc'
 import { Breadcrumbs } from '~/components/Breadcrumbs'
 import { FallbackBanner } from '~/components/FallbackBanner'
-import { useSiteConfig } from '~/utils/site-config'
+import { siteConfig } from '~/site.config'
 import type { LoadedBlogPost } from '~/utils/blog'
 
 type BlogArticleProps = {
@@ -30,7 +30,6 @@ type BlogArticleProps = {
 }
 
 export function BlogArticle({ post, lang, locale }: BlogArticleProps) {
-  const siteConfig = useSiteConfig()
   const { title, content, authors, published, filePath, isFallback } = post
 
   // Prepend byline to content (matches tanstack.com pattern)

package/template/app/components/Doc.tsx

@@ -11,7 +11,7 @@ import { MarkdownContent } from '~/components/markdown'
 import type { DocsConfig, MarkdownHeading } from '~/types'
 import { useLocalCurrentFramework } from './FrameworkSelect'
 import { useParams } from '@tanstack/react-router'
-import { useSiteConfig } from '~/utils/site-config'
+import { siteConfig } from '~/site.config'
 
 type DocProps = {
   title: string
@@ -51,8 +51,6 @@ export function Doc({
   isFallback = false,
   locale,
 }: DocProps) {
-  const siteConfig = useSiteConfig()
-
   // Extract headings synchronously during render to avoid hydration mismatch
   const { headings, markup } = React.useMemo(
     () => renderMarkdown(content),

package/template/app/routes/$lang.$project.$version.docs.$.tsx

@@ -15,7 +15,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = findProject(data.project)
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/$version/docs/$')({

package/template/app/routes/$lang.$project.$version.docs.framework.$framework.$.tsx

@@ -19,11 +19,13 @@ const fetchFrameworkDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
+    const projectConfig = findProject(data.project)
     return loadDoc(
       data.project,
       data.version,
       data.lang,
       `framework/${data.framework}/${data.slug}`,
+      projectConfig,
     )
   })
 

package/template/app/routes/$lang.$project.$version.docs.tsx

@@ -13,7 +13,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = findProject(data.project)
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/$version/docs')({

package/template/app/routes/$lang.$project.docs.$.tsx

@@ -13,7 +13,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = findProject(data.project)
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/docs/$')({

package/template/app/routes/$lang.$project.docs.tsx

@@ -13,7 +13,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = findProject(data.project)
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/$project/docs')({

package/template/app/routes/$lang.docs.$.tsx

@@ -13,7 +13,8 @@ const fetchDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
-    return loadDoc(data.project, data.version, data.lang, data.slug)
+    const projectConfig = getSingleProject()
+    return loadDoc(data.project, data.version, data.lang, data.slug, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/docs/$')({

package/template/app/routes/$lang.docs.framework.$framework.$.tsx

@@ -19,11 +19,13 @@ const fetchFrameworkDoc = createServerFn({ method: 'GET' })
   )
   .handler(async ({ data }) => {
     const { loadDoc } = await import('~/utils/docs.server')
+    const projectConfig = getSingleProject()
     return loadDoc(
       data.project,
       data.version,
       data.lang,
       `framework/${data.framework}/${data.slug}`,
+      projectConfig,
     )
   })
 

package/template/app/routes/$lang.docs.tsx

@@ -15,7 +15,8 @@ const fetchDocsConfig = createServerFn({ method: 'GET' })
   .inputValidator((data: { project: string; version: string }) => data)
   .handler(async ({ data }) => {
     const { loadDocsConfig } = await import('~/utils/docs.server')
-    return loadDocsConfig(data.project, data.version)
+    const projectConfig = getSingleProject()
+    return loadDocsConfig(data.project, data.version, projectConfig)
   })
 
 export const Route = createFileRoute('/$lang/docs')({

package/template/app/utils/content-loader.ts

@@ -64,6 +64,7 @@ function getTranslationCache(projectRoot: string): TranslationCache | null {
 
 export function createFsLoader(
   projectRoot: string,
+  docsRoot = 'content',
   urlMapper?: (filePath: string) => string,
 ): ContentLoader {
   /** Supported markdown extensions, in priority order. */
@@ -79,14 +80,20 @@ export function createFsLoader(
     lang: string,
     slug: string,
   ): { raw: string; filePath: string } | null {
+    // Resolve content base directory using docsRoot from site config.
+    // docsRoot encodes the project-specific path (e.g. 'content/query', 'content/docs').
+    // Convention: no /en/ subdir — English source files live directly under version/.
+    // Non-English comes from .cache/ (translation assembly).
     const baseDirs = [
-      resolve(projectRoot, 'content', project, version, lang),
-      resolve(projectRoot, 'content', project, lang),
-      resolve(projectRoot, 'content', version, lang),
-      resolve(projectRoot, 'content', lang),
-      // Flat structure (no lang subdir): content/{version}/ directly
+      resolve(projectRoot, docsRoot, version),
+      resolve(projectRoot, docsRoot),
+      // Fallback: try content/{project}/{version} pattern
       resolve(projectRoot, 'content', project, version),
       resolve(projectRoot, 'content', version),
+      // Legacy: with lang subdir
+      resolve(projectRoot, 'content', project, version, lang),
+      resolve(projectRoot, docsRoot, version, lang),
+      resolve(projectRoot, docsRoot, lang),
     ]
 
     if (!urlMapper) {

package/template/app/utils/docs.server.ts

@@ -62,7 +62,7 @@ export function setContentLoader(loader: ContentLoader) {
 
 /**
  * Load a document with i18n fallback.
- * When projectConfig has urlMapper, creates a mapper-aware loader.
+ * Uses docsRoot from projectConfig to resolve content paths.
  */
 export async function loadDoc(
   project: string,
@@ -71,11 +71,9 @@ export async function loadDoc(
   slug: string,
   projectConfig?: ProjectConfig,
 ): Promise<LoadedDoc> {
-  if (projectConfig?.urlMapper) {
-    const loader = createFsLoader(getProjectRoot(), projectConfig.urlMapper)
-    return loader.loadDoc(project, version, lang, slug)
-  }
-  return getLoader().loadDoc(project, version, lang, slug)
+  const docsRoot = projectConfig?.docsRoot || 'content'
+  const loader = createFsLoader(getProjectRoot(), docsRoot, projectConfig?.urlMapper)
+  return loader.loadDoc(project, version, lang, slug)
 }
 
 /**
@@ -91,11 +89,13 @@ export async function loadDocsConfig(
     return loadFilesystemSidebar(project, version, projectConfig)
   }
 
-  const config = await getLoader().loadDocsConfig(project, version)
+  const docsRoot = projectConfig?.docsRoot || 'content'
+  const loader = createFsLoader(getProjectRoot(), docsRoot)
+  const config = await loader.loadDocsConfig(project, version)
   if (config) return config
 
   // Auto-scan fallback (filesystem only)
-  return autoScanDocs(getProjectRoot(), project, version)
+  return autoScanDocs(getProjectRoot(), docsRoot, project, version)
 }
 
 /** Generate sidebar from filesystem using numeric prefix ordering. */
@@ -105,14 +105,11 @@ function loadFilesystemSidebar(
   projectConfig: ProjectConfig,
 ): DocsConfig {
   const root = getProjectRoot()
+  const docsRoot = projectConfig.docsRoot || 'content'
   const candidates = [
-    resolve(root, 'content', project, version, 'en'),
-    resolve(root, 'content', project, 'en'),
-    resolve(root, 'content', version, 'en'),
-    resolve(root, 'content', 'en'),
-    // Flat structure (no lang subdir)
+    resolve(root, docsRoot, version),
+    resolve(root, docsRoot),
     resolve(root, 'content', project, version),
-    resolve(root, 'content', version),
   ]
   for (const dir of candidates) {
     if (existsSync(dir) && statSync(dir).isDirectory()) {
@@ -124,20 +121,18 @@ function loadFilesystemSidebar(
 }
 
 /**
- * Auto-generate sidebar config by scanning .md files in the content directory.
+ * Auto-generate sidebar config by scanning .md/.mdx files in the content directory.
  */
 function autoScanDocs(
   root: string,
+  docsRoot: string,
   project: string,
   version: string,
 ): DocsConfig {
   const candidates = [
-    resolve(root, 'content', project, version, 'en'),
-    resolve(root, 'content', project, 'en'),
-    resolve(root, 'content', version, 'en'),
-    resolve(root, 'content', 'en'),
+    resolve(root, docsRoot, version),
+    resolve(root, docsRoot),
     resolve(root, 'content', project, version),
-    resolve(root, 'content', version),
   ]
 
   for (const dir of candidates) {

package/template/content/docs-i18n/en/architecture.md

@@ -7,33 +7,146 @@ description: How docs-i18n works internally -- the translation pipeline, AST par
 
 This document explains how docs-i18n works internally. Understanding the pipeline helps you tune configuration, debug issues, and contribute to the project.
 
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        docs-i18n ecosystem                      │
+│                                                                 │
+│  ┌──────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐  │
+│  │ CLI      │    │ Admin     │    │ Template │    │ Runtime │  │
+│  │          │    │ Dashboard │    │ (Site)   │    │ (D1)    │  │
+│  │ translate│    │ (pre-     │    │ TanStack │    │ CF      │  │
+│  │ rescan   │    │  built)   │    │ Start    │    │ Workers │  │
+│  │ assemble │    │           │    │          │    │         │  │
+│  │ status   │    │ Web UI    │    │ SSR docs │    │ Edge    │  │
+│  └────┬─────┘    └─────┬─────┘    └────┬─────┘    └────┬────┘  │
+│       │                │               │               │        │
+│       └────────┬───────┴───────┬───────┘               │        │
+│                │               │                       │        │
+│         ┌──────▼──────┐  ┌─────▼──────┐          ┌─────▼─────┐  │
+│         │ SQLite      │  │ Content    │          │ D1        │  │
+│         │ .cache/     │  │ content/   │          │ (cloud)   │  │
+│         │ translations│  │ {project}/ │          │           │  │
+│         │ .db         │  │ {version}/ │          │ translate │  │
+│         └─────────────┘  └────────────┘          │ ions      │  │
+│                                                  └───────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Monorepo Structure
+
+```
+docs-i18n/
+  packages/
+    core/          ← Published as "docs-i18n" on npm
+    │  src/
+    │    cli.ts         CLI entry point
+    │    core/          Parser, cache, assembler, translator
+    │    commands/      translate, rescan, assemble, status, upload
+    │  dist/            Built output
+    │
+    admin/         ← Pre-built admin dashboard
+    │  app/             TanStack Start React app
+    │  server/          Server functions (status, jobs, models)
+    │  dist/            Pre-built (zero-install runtime)
+    │  serve.mjs        Node.js HTTP adapter
+    │
+    template/      ← Docs site template (built per-project)
+       app/             TanStack Start React app
+       content/         Demo content + docs-i18n's own docs
+```
+
 ## Translation Pipeline
 
-The end-to-end flow is:
-
-```
-Source files (EN)
-    |
-    v
-[1. Normalize] -- Ensure JSX tags are separated by blank lines
-    |
-    v
-[2. Parse] -- remark AST -> flat list of typed nodes
-    |
-    v
-[3. Hash] -- MD5 of each translatable node's text
-    |
-    v
-[4. Chunk] -- Group nodes into chunks that fit the LLM context window
-    |
-    v
-[5. Translate] -- Send JSON to LLM, receive JSON translations
-    |
-    v
-[6. Cache] -- Store translations in SQLite keyed by (lang, md5)
-    |
-    v
-[7. Assemble] -- EN source + cache -> translated output files
+```
+Source .md/.mdx files (English)
+    │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  1. Normalize                                     │
+│  Ensure JSX tags (<AppOnly> etc.) are separated  │
+│  by blank lines for correct AST parsing          │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  2. Parse (remark AST)                            │
+│  .md/.mdx → flat list of typed nodes             │
+│  heading | paragraph | list | code | html | ...  │
+│  Each node: { type, rawText, needsTranslation }  │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  3. Hash (MD5)                                    │
+│  "## Installation" → "a1b2c3d4..."               │
+│  Same content = same key = deduplicated           │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  4. Smart Chunking                                │
+│  Group nodes into chunks fitting LLM context     │
+│  Input budget + output budget + language mult.   │
+│  CJK: 2.5x │ Cyrillic: 2.0x │ Chinese: 1.5x    │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  5. LLM Translation                               │
+│  Send: { nodes: [{ key, type, text }] }          │
+│  Recv: { "a1b2c3": "翻译结果" }                   │
+│  JSON repair + key recovery + retry + rotation   │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  6. Cache (SQLite)                                │
+│  INSERT INTO translations (lang, key, value)     │
+│  WAL mode │ concurrent-safe │ instant writes     │
+└──────────────────┬───────────────────────────────┘
+                   │
+    ▼
+┌──────────────────────────────────────────────────┐
+│  7. Assemble                                      │
+│  English source + cached translations            │
+│  → translated .md/.mdx files                     │
+│  Missing translations → fallback to English      │
+└──────────────────────────────────────────────────┘
+```
+
+## Content Structure Convention
+
+```
+your-project/
+  content/                          ← English source (no /en/ subdir)
+    {project}/{version}/            ← e.g. query/v5/ or nextjs/latest/
+      overview.md
+      guides/routing.md
+      ...
+
+  .cache/
+    translations.db                 ← SQLite cache (all languages)
+    content/{version}/{lang}/       ← assembled translations
+      overview.md
+      guides/routing.md
+
+  docs-i18n.config.ts               ← translation config
+  site.config.ts                    ← site template config
+```
+
+The site template resolves content as:
+```
+Request: /zh-hans/query/v5/docs/overview
+                   │     │        │
+                   │     │        └─ slug
+                   │     └─ version
+                   └─ project
+
+  English: content/query/v5/overview.md              ← direct read
+  zh-hans: .cache/ → translations.db → assemble()   ← from cache
+  Fallback: English source (isFallback: true)
 ```
 
 ## Step 1: Normalization

package/template/content/docs-i18n/en/cli.md

@@ -271,6 +271,15 @@ For non-English languages, the site automatically loads translations from the `.
 
 ### Full translation pipeline
 
+```
+rescan ──→ status ──→ translate ──→ assemble ──→ site dev
+  │           │           │            │            │
+  ▼           ▼           ▼            ▼            ▼
+ Index     Progress    Send to     EN + cache    Serve
+ source     bars       LLM, cache   → output    multilingual
+ files                 results      files        docs site
+```
+
 ```bash
 # 1. Scan source files
 docs-i18n rescan
@@ -281,8 +290,11 @@ docs-i18n status
 # 3. Translate
 docs-i18n translate --lang zh-hans
 
-# 4. Assemble output
+# 4. Assemble output (optional — site does this at runtime)
 docs-i18n assemble --lang zh-hans
+
+# 5. Start docs site
+docs-i18n site
 ```
 
 ### Translate a single file for review

package/template/content/docs-i18n/en/configuration.md

@@ -62,9 +62,20 @@ projects: {
 
 The version key (e.g., `latest`, `v1`) is used to organize translations in the cache and in assembled output. The source path points to the directory containing your English markdown/MDX files.
 
-**Single project:**
+```
+Content directory convention:
+
+  content/                        ← English source (no /en/ subdir)
+    {project}/{version}/          ← source path in config
+      file.md
+      subdir/file.mdx
+
+  .cache/
+    translations.db               ← all translations
+    content/{version}/{lang}/     ← assembled output
+```
 
-When you have a single project, version keys are used directly in the database and output paths (e.g., `latest`).
+**Single project:**
 
 ```ts
 projects: {
@@ -74,6 +85,12 @@ projects: {
 }
 ```
 
+```
+content/docs/              ← source files (English)
+  getting-started.md
+  api-reference.md
+```
+
 **Multi-project:**
 
 When you have multiple projects, keys become compound: `project/version` (e.g., `query/latest`, `table/v1`).
@@ -82,7 +99,7 @@ When you have multiple projects, keys become compound: `project/version` (e.g.,
 projects: {
   query: {
     sources: {
-      latest: 'content/query/latest',
+      v5: 'content/query/v5',
       v4: 'content/query/v4',
     },
   },
@@ -91,14 +108,16 @@ projects: {
       latest: 'content/table/latest',
     },
   },
-  blog: {
-    sources: {
-      latest: 'content/blog',
-    },
-  },
 }
 ```
 
+```
+content/
+  query/v5/overview.md     ← query project, v5
+  query/v4/overview.md     ← query project, v4
+  table/latest/overview.md ← table project
+```
+
 ### `languages`
 
 **Required.** An array of target language codes to translate into. These codes are used as identifiers in the cache and output directories.

package/template/content/docs-i18n/en/deployment.md

@@ -100,11 +100,32 @@ jobs:
       - run: npx docs-i18n translate --lang zh-hans --dry-run
 ```
 
-## Admin Dashboard Deployment
+## Deployment Architecture
 
-The admin dashboard is a TanStack Start application that runs locally. It is designed for development use, not production deployment.
+```
+┌──────────────────────────────────────────────────────────┐
+│  Development (local)                                      │
+│                                                          │
+│  docs-i18n admin ──→ Pre-built Node.js server (port 3456)│
+│  docs-i18n site  ──→ Vite dev server (port 3000)         │
+│                      ↕ reads content/ + .cache/           │
+└──────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────┐
+│  Production (Cloudflare Workers)                          │
+│                                                          │
+│  docs-i18n site build ──→ .output/                       │
+│  docs-i18n site upload ──→ D1 (translations)             │
+│  docs-i18n site deploy ──→ CF Workers (SSR)              │
+│                                                          │
+│  Request → Worker → fetch EN content → D1 translate      │
+│                   → SSR render → response                │
+└──────────────────────────────────────────────────────────┘
+```
 
-To start it:
+## Admin Dashboard
+
+The admin dashboard is pre-built and requires no additional dependencies. It runs as a local Node.js server.
 
 ```bash
 npx docs-i18n admin
@@ -112,15 +133,7 @@ npx docs-i18n admin
 npx docs-i18n admin --port 4000
 ```
 
-The dashboard starts a Vite dev server pointed at the `src/admin` directory within the docs-i18n package. It reads your `docs-i18n.config.ts` to discover projects, versions, and languages.
-
-**Prerequisites:**
-
-Your project must have `vite` and `@vitejs/plugin-react` installed as dev dependencies:
-
-```bash
-npm install -D vite @vitejs/plugin-react
-```
+It reads your `docs-i18n.config.ts` to discover projects, versions, and languages.
 
 ## Runtime Translation with D1
 

package/template/content/docs-i18n/en/getting-started.md

@@ -18,11 +18,32 @@ Key characteristics:
 - **Admin dashboard** -- web UI for monitoring progress, managing jobs, and previewing translations.
 - **Runtime serve** -- optional D1-compatible translator for SSR sites on Cloudflare Workers.
 
+## How It Works
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────────┐
+│ Your docs   │     │ docs-i18n   │     │ Translated   │
+│ (English)   │────→│ translate   │────→│ docs (cache) │
+│ .md / .mdx  │     │ via LLM     │     │ .cache/      │
+└─────────────┘     └─────────────┘     └──────┬───────┘
+                                               │
+                    ┌─────────────┐             │
+                    │ docs-i18n   │◄────────────┘
+                    │ site        │
+                    │ (dev/build) │──→ Multilingual docs site
+                    └─────────────┘
+```
+
+**Workflow:**
+1. Write docs in English (`.md` or `.mdx`)
+2. `docs-i18n translate` sends new/changed content to LLM, caches results in SQLite
+3. `docs-i18n site` serves a multilingual docs site (assembles translations at runtime)
+4. `docs-i18n admin` provides a web UI to monitor progress and manage jobs
+
 ## Requirements
 
 - Node.js 20+ or Bun
 - An API key for an LLM provider (OpenRouter, OpenAI, or Anthropic)
-- For the admin dashboard: `vite` and `@vitejs/plugin-react` as dev dependencies
 
 ## Installation