docs-i18n 0.9.2 → 0.11.0

package/admin/server/services/d1-status.ts

@@ -0,0 +1,282 @@
+/**
+ * D1-backed status service for CF Workers deployment.
+ *
+ * Queries the same sources/source_files/translations tables as the local
+ * TranslationCache, but via D1 instead of better-sqlite3.
+ *
+ * This is read-only — the admin dashboard on CF Workers can view
+ * translation status but cannot run translate jobs or modify the cache.
+ */
+
+function getD1(): D1Database | null {
+  try {
+    return (globalThis as any).__D1_DB ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function requireD1(): D1Database {
+  const db = getD1();
+  if (!db) throw new Error('D1 database not available');
+  return db;
+}
+
+export async function d1GetVersions(): Promise<string[]> {
+  const db = requireD1();
+  const result = await db
+    .prepare('SELECT DISTINCT version FROM source_files ORDER BY version')
+    .all<{ version: string }>();
+  return result.results.map((r) => r.version);
+}
+
+export async function d1GetLangs(): Promise<string[]> {
+  const db = requireD1();
+  const result = await db
+    .prepare('SELECT DISTINCT lang FROM translations ORDER BY lang')
+    .all<{ lang: string }>();
+  return result.results.map((r) => r.lang);
+}
+
+export async function d1SectionStats(
+  version: string,
+  lang: string,
+): Promise<
+  {
+    section: string;
+    totalFiles: number;
+    translatedFiles: number;
+    totalNodes: number;
+    translatedNodes: number;
+  }[]
+> {
+  const db = requireD1();
+  const result = await db
+    .prepare(
+      `
+      WITH file_coverage AS (
+        SELECT
+          sf.file,
+          CASE
+            WHEN sf.file LIKE 'docs/%' THEN 'docs'
+            WHEN sf.file LIKE 'blog/%' THEN 'blog'
+            WHEN sf.file LIKE 'learn/%' THEN 'learn'
+            ELSE 'other'
+          END as section,
+          COUNT(DISTINCT sf.key) as total_nodes,
+          COUNT(DISTINCT t.key) as translated_nodes
+        FROM source_files sf
+        LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+        WHERE sf.version = ?
+        GROUP BY sf.file
+      )
+      SELECT
+        section,
+        COUNT(*) as totalFiles,
+        SUM(CASE WHEN translated_nodes = total_nodes THEN 1 ELSE 0 END) as translatedFiles,
+        SUM(total_nodes) as totalNodes,
+        SUM(translated_nodes) as translatedNodes
+      FROM file_coverage
+      GROUP BY section
+      ORDER BY section
+    `,
+    )
+    .bind(lang, version)
+    .all<{
+      section: string;
+      totalFiles: number;
+      translatedFiles: number;
+      totalNodes: number;
+      translatedNodes: number;
+    }>();
+  return result.results;
+}
+
+export async function d1SourceCount(version: string): Promise<number> {
+  const db = requireD1();
+  const result = await db
+    .prepare(
+      'SELECT COUNT(DISTINCT key) as count FROM source_files WHERE version = ?',
+    )
+    .bind(version)
+    .first<{ count: number }>();
+  return result?.count ?? 0;
+}
+
+export async function d1FileCoverage(
+  version: string,
+  lang: string,
+): Promise<{ file: string; total: number; translated: number }[]> {
+  const db = requireD1();
+  const result = await db
+    .prepare(
+      `
+      SELECT
+        sf.file,
+        COUNT(DISTINCT sf.key) as total,
+        COUNT(DISTINCT t.key) as translated
+      FROM source_files sf
+      LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+      WHERE sf.version = ?
+      GROUP BY sf.file
+      ORDER BY sf.file
+    `,
+    )
+    .bind(lang, version)
+    .all<{ file: string; total: number; translated: number }>();
+  return result.results;
+}
+
+export async function d1FileDetail(
+  version: string,
+  lang: string,
+  file: string,
+): Promise<
+  {
+    key: string;
+    source: string;
+    type: string;
+    translation: string | null;
+    line: number;
+  }[]
+> {
+  const db = requireD1();
+  const result = await db
+    .prepare(
+      `
+      SELECT
+        s.key,
+        s.text as source,
+        s.type,
+        t.value as translation,
+        sf.line
+      FROM source_files sf
+      JOIN sources s ON s.key = sf.key
+      LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+      WHERE sf.version = ? AND sf.file = ?
+      ORDER BY sf.line
+    `,
+    )
+    .bind(lang, version, file)
+    .all<{
+      key: string;
+      source: string;
+      type: string;
+      translation: string | null;
+      line: number;
+    }>();
+  return result.results;
+}
+
+export async function d1GetTranslation(
+  lang: string,
+  key: string,
+): Promise<string | null> {
+  const db = requireD1();
+  const result = await db
+    .prepare('SELECT value FROM translations WHERE lang = ? AND key = ?')
+    .bind(lang, key)
+    .first<{ value: string }>();
+  return result?.value ?? null;
+}
+
+export async function d1DeleteTranslation(
+  lang: string,
+  key: string,
+): Promise<boolean> {
+  const db = requireD1();
+  const result = await db
+    .prepare('DELETE FROM translations WHERE lang = ? AND key = ?')
+    .bind(lang, key)
+    .run();
+  return (result.meta?.changes ?? 0) > 0;
+}
+
+export async function d1GetOverview(
+  versions: string[],
+  langs: string[],
+): Promise<
+  Record<
+    string,
+    {
+      enFileCount: number;
+      langs: Record<
+        string,
+        {
+          sections: Record<string, any>;
+          totalFiles: number;
+          translatedFiles: number;
+          totalNodes: number;
+          translatedNodes: number;
+        }
+      >;
+    }
+  >
+> {
+  const db = requireD1();
+  const result: Record<string, any> = {};
+
+  for (const version of versions) {
+    // Count unique files for this version
+    const fileCountResult = await db
+      .prepare(
+        'SELECT COUNT(DISTINCT file) as count FROM source_files WHERE version = ?',
+      )
+      .bind(version)
+      .first<{ count: number }>();
+    const enFileCount = fileCountResult?.count ?? 0;
+
+    const langStats: Record<string, any> = {};
+    for (const lang of langs) {
+      const sections = await d1SectionStats(version, lang);
+      let totalFiles = 0,
+        translatedFiles = 0,
+        totalNodes = 0,
+        translatedNodes = 0;
+      const sectionMap: Record<string, any> = {};
+      for (const s of sections) {
+        sectionMap[s.section] = s;
+        totalFiles += s.totalFiles;
+        translatedFiles += s.translatedFiles;
+        totalNodes += s.totalNodes;
+        translatedNodes += s.translatedNodes;
+      }
+      langStats[lang] = {
+        sections: sectionMap,
+        totalFiles,
+        translatedFiles,
+        totalNodes,
+        translatedNodes,
+      };
+    }
+    result[version] = { enFileCount, langs: langStats };
+  }
+
+  return result;
+}
+
+/**
+ * Get file blocks from D1 — returns source nodes with their translations,
+ * in line order. Note: without filesystem access, we can only return
+ * translatable blocks (no gap/whitespace blocks between them).
+ */
+export async function d1GetFileBlocks(
+  version: string,
+  lang: string,
+  file: string,
+): Promise<
+  {
+    md5: string | null;
+    type: string;
+    source: string;
+    translation: string | null;
+  }[]
+> {
+  const detail = await d1FileDetail(version, lang, file);
+  return detail.map((row) => ({
+    md5: row.key,
+    type: row.type,
+    source: row.source,
+    translation: row.translation,
+  }));
+}

package/admin/vite.config.ts

@@ -3,24 +3,38 @@ import { defineConfig } from 'vite';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
 import react from '@vitejs/plugin-react';
 
+// CF Workers deploy mode: DOCS_I18N_CF=1 enables @cloudflare/vite-plugin
+const isCfBuild = process.env.DOCS_I18N_CF === '1';
+
+const plugins: any[] = [
+  tanstackStart({
+    srcDirectory: 'app',
+  }),
+  react(),
+];
+
+// Add Cloudflare plugin for CF Workers builds
+if (isCfBuild) {
+  const { cloudflare } = await import('@cloudflare/vite-plugin');
+  plugins.unshift(cloudflare({ viteEnvironment: { name: 'ssr' } }));
+}
+
 export default defineConfig({
-  plugins: [
-    tanstackStart({
-      srcDirectory: 'app',
-    }),
-    react(),
-  ],
+  plugins,
   // Bundle all deps into server build so it can run without node_modules
-  environments: {
-    ssr: {
-      build: {
-        rollupOptions: {
-          external: ['node:*'],
+  // (Only for non-CF builds; CF plugin manages its own SSR environment)
+  ...(!isCfBuild && {
+    environments: {
+      ssr: {
+        build: {
+          rollupOptions: {
+            external: [/^node:/, 'better-sqlite3'],
+          },
+        },
+        resolve: {
+          noExternal: true,
         },
-      },
-      resolve: {
-        noExternal: true,
       },
     },
-  },
+  }),
 });

package/admin/wrangler.jsonc

@@ -0,0 +1,16 @@
+{
+  "name": "docs-i18n-admin",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "main": "./app/worker.ts",
+  "assets": {
+    "directory": "dist/client"
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "docs-i18n-db",
+      "database_id": "597ff8e0-36fd-4bd5-a3fd-8f9e5bd14662"
+    }
+  ]
+}

package/package.json

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

package/template/app/components/markdown/Markdown.tsx

@@ -211,6 +211,12 @@ export const Markdown = React.memo(function Markdown({
       return null
     }
 
-    return parse(rendered.markup, options)
+    try {
+      return parse(rendered.markup, options)
+    } catch {
+      // Fallback: render raw HTML when DOM-based parser is unavailable (e.g., CF Workers)
+      // Client-side hydration will re-render correctly with full DOM APIs
+      return <div dangerouslySetInnerHTML={{ __html: rendered.markup }} />
+    }
   }, [rendered.markup, options])
 })

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

@@ -9,8 +9,9 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { resolve, relative, join } from 'node:path'
 import matter from 'gray-matter'
 import type { LoadedDoc, DocsConfig, DocsConfigItem, ProjectConfig } from '~/types'
-import { type ContentLoader, createFsLoader } from './content-loader'
+import { type ContentLoader, createFsLoader, createD1Loader } from './content-loader'
 import { generateSidebarFromFilesystem } from './sidebar-generator'
+import { createDb } from '~/db'
 
 /**
  * Get the project root directory.
@@ -60,6 +61,38 @@ export function setContentLoader(loader: ContentLoader) {
   _loader = loader
 }
 
+/** Cached D1 reference (or false if not available). */
+let _d1Cache: D1Database | false | undefined
+
+/**
+ * Try to get D1 binding from Cloudflare Workers environment.
+ * Returns null if not running on CF Workers.
+ */
+function getD1(): D1Database | null {
+  if (_d1Cache !== undefined) return _d1Cache || null
+  try {
+    // globalThis.__D1_DB is set by the worker entry (app/worker.ts)
+    const db = (globalThis as any).__D1_DB
+    if (db) {
+      _d1Cache = db
+      return db
+    }
+  } catch {}
+  _d1Cache = false
+  return null
+}
+
+/**
+ * Get a content loader, auto-detecting D1 on CF Workers.
+ */
+function getContentLoader(docsRoot?: string, urlMapper?: (filePath: string) => string): ContentLoader {
+  const d1 = getD1()
+  if (d1) {
+    return createD1Loader(createDb(d1))
+  }
+  return createFsLoader(getProjectRoot(), docsRoot, urlMapper)
+}
+
 /**
  * Load a document with i18n fallback.
  * Uses docsRoot from projectConfig to resolve content paths.
@@ -72,7 +105,7 @@ export async function loadDoc(
   projectConfig?: ProjectConfig,
 ): Promise<LoadedDoc> {
   const docsRoot = projectConfig?.docsRoot || 'content'
-  const loader = createFsLoader(getProjectRoot(), docsRoot, projectConfig?.urlMapper)
+  const loader = getContentLoader(docsRoot, projectConfig?.urlMapper)
   return loader.loadDoc(project, version, lang, slug)
 }
 
@@ -90,11 +123,11 @@ export async function loadDocsConfig(
   }
 
   const docsRoot = projectConfig?.docsRoot || 'content'
-  const loader = createFsLoader(getProjectRoot(), docsRoot)
+  const loader = getContentLoader(docsRoot)
   const config = await loader.loadDocsConfig(project, version)
   if (config) return config
 
-  // Auto-scan fallback (filesystem only)
+  // Auto-scan fallback (filesystem only, won't work on CF Workers)
   return autoScanDocs(getProjectRoot(), docsRoot, project, version)
 }
 

package/template/app/worker.ts

@@ -0,0 +1,16 @@
+/**
+ * Cloudflare Workers entry point.
+ * Re-exports TanStack Start's server entry as a CF Worker fetch handler.
+ * Injects D1 binding into globalThis for server-side content loading.
+ */
+import handler from '@tanstack/react-start/server-entry'
+
+export default {
+  async fetch(request: Request, env: any, ctx: any) {
+    // Expose D1 binding to server-side code via globalThis
+    if (env?.DB) {
+      ;(globalThis as any).__D1_DB = env.DB
+    }
+    return handler.fetch(request)
+  },
+}

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

@@ -226,7 +226,7 @@ docs-i18n site [subcommand] [options]
 
 | Subcommand | Description |
 | --- | --- |
-| `dev` (default) | Start the Vite dev server with hot reload |
+| `dev` (default) | Start the site server (pre-built or Vite dev) |
 | `build` | Build the site for production |
 | `upload` | Upload content and translations to Cloudflare D1 |
 | `deploy` | Deploy to Cloudflare Workers |
@@ -236,16 +236,20 @@ docs-i18n site [subcommand] [options]
 | Flag | Default | Description |
 | --- | --- | --- |
 | `--port <n>` | 3000 | Port for the dev server |
+| `--custom` | false | Force Vite dev mode (skip pre-built server) |
 | `--db <name>` | `docs-i18n-db` | D1 database name (for `upload`) |
 
 **Examples:**
 
 ```bash
-# Start dev server
+# Start site (uses pre-built server for instant startup)
 docs-i18n site
 
 # Start on custom port
-docs-i18n site dev --port 4000
+docs-i18n site --port 4000
+
+# Force Vite dev mode (HMR, custom components)
+docs-i18n site --custom
 
 # Build for production
 docs-i18n site build
@@ -259,9 +263,9 @@ docs-i18n site deploy
 
 **How it works:**
 
-The `site` command does not require a `docs-i18n.config.ts`. It reads the `site.config.ts` file from your project root to configure the documentation site (project names, colors, locales, etc.).
+The `site` command reads `site.config.ts` from your project root to configure the documentation site (project names, colors, locales, etc.).
 
-On first run, the template's dependencies are automatically installed. The dev server uses Vite with the consumer's `site.config.ts` aliased into the template for customization.
+By default, the site starts instantly using the pre-built Node.js server (no `npm install` needed). The pre-built server uses `jiti` to load your `site.config.ts` at runtime. Use `--custom` to fall back to Vite dev mode with hot reload when you need custom React components or live editing.
 
 For non-English languages, the site automatically loads translations from the `.cache/translations.db` SQLite cache and assembles them at runtime.