docs-i18n 0.1.0

package/dist/false-JGP4AGWN.js

@@ -0,0 +1,7 @@
+import {
+  false_default
+} from "./chunk-O35QHRY6.js";
+import "./chunk-AKLW2MUS.js";
+export {
+  false_default as default
+};

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+/**
+ * docs-i18n configuration schema.
+ * Each project provides a `docs-i18n.config.ts` file.
+ */
+interface ProjectConfig {
+    /** Map of version → source directory (relative to project root) */
+    sources: Record<string, string>;
+}
+interface DocsI18nConfig {
+    /** Project definitions — key is project ID */
+    projects: Record<string, ProjectConfig>;
+    /** Languages to translate to */
+    languages: string[];
+    /** Cache/database directory (default: '.cache') */
+    cacheDir?: string;
+    /** Frontmatter fields to translate (supports dot notation for nested) */
+    translatableFields?: string[];
+    /** LLM configuration */
+    llm?: {
+        provider?: 'openrouter' | 'openai' | 'anthropic';
+        model?: string;
+        contextLength?: number;
+        maxTokens?: number;
+    };
+    /** Project context injected into LLM system prompt */
+    context?: string;
+    /** File patterns to include (default: ['**\/*.mdx', '**\/*.md']) */
+    include?: string[];
+    /** Hook called after translation completes */
+    onTranslated?: (info: {
+        project: string;
+        version: string;
+        lang: string;
+    }) => Promise<void>;
+}
+declare function defineConfig(config: DocsI18nConfig): DocsI18nConfig;
+/** Load config from file */
+declare function loadConfig(path?: string): Promise<DocsI18nConfig>;
+/** Flatten projects into version entries (project/version → source path) */
+declare function flattenSources(config: DocsI18nConfig): Array<{
+    project: string;
+    version: string;
+    sourcePath: string;
+    /** Compound key for DB: "project/version" or just "version" if single project */
+    versionKey: string;
+}>;
+
+interface ParsedNode {
+    /** AST node type: paragraph, heading, code, list, blockquote, html, thematicBreak */
+    type: string;
+    /** Raw text content extracted from the original (normalized) content */
+    rawText: string;
+    /** Whether this node contains text that needs translation */
+    needsTranslation: boolean;
+    /** MD5 hash of the content (only set for translatable nodes) */
+    md5?: string;
+    /** Start offset in the normalized content */
+    startOffset: number;
+    /** End offset in the normalized content */
+    endOffset: number;
+}
+/**
+ * Parse MDX content into a flat list of classified AST nodes.
+ * Applies normalize() preprocessing before parsing.
+ *
+ * Frontmatter (---\n...\n---) is detected and emitted as a single
+ * "frontmatter" node spanning from the opening --- to closing ---.
+ */
+declare function parseMdx(rawContent: string): ParsedNode[];
+
+interface SqliteStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+interface SqliteDatabase {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): void;
+    pragma(pragma: string): unknown;
+    transaction<T>(fn: () => T): () => T;
+    close(): void;
+}
+
+interface CacheEntry {
+    v: string;
+    /** Source locations: "relative/path/to/file.mdx:lineNumber" */
+    src: string[];
+}
+/**
+ * Translation cache backed by SQLite.
+ *
+ * Schema:
+ *   sources(key PK, text, type)            — EN source texts
+ *   source_files(key, file, line, version)  — which files use each source node
+ *   translations(lang, key, value, ...)     — translated texts per language
+ *
+ * All writes are immediate (no separate save step).
+ * WAL mode enables concurrent readers + single writer.
+ */
+declare class TranslationCache {
+    db: SqliteDatabase;
+    private cacheDir;
+    private _stmts?;
+    constructor(cacheDir: string);
+    private get stmts();
+    /**
+     * Load cache for a language. No-op for SQLite (data is always available).
+     * Kept for API compatibility.
+     */
+    load(_lang: string): void;
+    /**
+     * Save cache for a language. No-op for SQLite (writes are immediate).
+     * Kept for API compatibility.
+     */
+    save(_lang: string): void;
+    /** Get a cached translation */
+    get(lang: string, md5: string): string | undefined;
+    /** Set a cached translation (writes immediately to disk) */
+    set(lang: string, md5: string, translation: string): void;
+    /**
+     * Set a cached translation with its EN source text.
+     * This also stores the source in the `sources` table for dashboard use.
+     */
+    setWithSource(lang: string, md5: string, translation: string, sourceText: string, sourceType?: string): void;
+    /** Delete a cached translation */
+    delete(lang: string, md5: string): boolean;
+    /** Iterate all entries for a language */
+    entries(lang: string): IterableIterator<[string, CacheEntry]>;
+    /** Get all cached keys for a language as a Set (fast for coverage checks) */
+    keys(lang: string): Set<string>;
+    /** Remove entries not in the provided set of md5s */
+    prune(lang: string, usedMd5s: Set<string>): number;
+    /** Get cache stats for a language */
+    stats(lang: string): {
+        size: number;
+    };
+    /**
+     * Update source locations for a md5 hash.
+     * In SQLite mode, this inserts into source_files table.
+     */
+    updateSource(_lang: string, md5: string, filePath: string, line: number, version?: string): void;
+    /** Clear all source file mappings for a version (call before a full rebuild) */
+    clearSources(_lang: string, version?: string): void;
+    /** Store an EN source text in the sources table */
+    setSource(md5: string, text: string, type?: string): void;
+    /** Get an EN source text from the sources table */
+    getSource(md5: string): {
+        text: string;
+        type: string;
+    } | undefined;
+    /**
+     * Get all untranslated source keys for a language and version.
+     * Returns keys with their EN source text and type.
+     */
+    untranslatedKeys(lang: string, version?: string, limit?: number, files?: string[]): {
+        key: string;
+        text: string;
+        type: string;
+    }[];
+    /** Get translation stats for all languages */
+    allLangStats(): {
+        lang: string;
+        count: number;
+    }[];
+    /**
+     * Get file-level coverage for a version and language.
+     * Returns how many source nodes each file has and how many are translated.
+     */
+    fileCoverage(version: string, lang: string): {
+        file: string;
+        total: number;
+        translated: number;
+    }[];
+    /**
+     * Get node-level detail for a specific file: EN source + translation side by side.
+     */
+    fileDetail(version: string, lang: string, file: string): {
+        key: string;
+        source: string;
+        type: string;
+        translation: string | null;
+        line: number;
+    }[];
+    /** Get total source node count for a version */
+    sourceCount(version: string): number;
+    /**
+     * Get section-level stats for a version and language.
+     * Section is derived from file path prefix (docs/, blog/, learn/).
+     */
+    sectionStats(version: string, lang: string): {
+        section: string;
+        totalFiles: number;
+        translatedFiles: number;
+        totalNodes: number;
+        translatedNodes: number;
+    }[];
+    /** Export cache to JSONL format (for backward compatibility / git tracking) */
+    exportJsonl(lang: string, outputPath: string): number;
+    /** Import translations from a JSONL file */
+    importJsonl(lang: string, inputPath: string): number;
+    /** Export a readable markdown index for IDE navigation */
+    exportIndex(lang: string): void;
+    /** Close the database connection */
+    close(): void;
+}
+
+interface AssembleResult {
+    /** The assembled file content */
+    content: string;
+    /** Whether all translatable nodes were found in cache */
+    allCached: boolean;
+    /** Number of translatable nodes found in cache */
+    cachedCount: number;
+    /** Number of translatable nodes not in cache */
+    uncachedCount: number;
+    /** Total number of translatable nodes */
+    totalTranslatable: number;
+    /** The parsed nodes for reference */
+    parsedNodes: ParsedNode[];
+}
+/**
+ * Assemble a target-language file from source content + translation cache.
+ *
+ * - Cached translations replace the original text
+ * - Uncached nodes are wrapped in NEEDS_TRANSLATION markers
+ * - Code, HTML tags, thematicBreak are kept as-is
+ */
+declare function assemble(rawContent: string, lang: string, cache: TranslationCache, 
+/** Relative file path for source tracking (e.g. "docs/01-app/installation.mdx") */
+sourceFilePath?: string, 
+/** If true, use EN source text as fallback instead of NEEDS_TRANSLATION markers */
+fallbackToSource?: boolean): AssembleResult;
+
+/**
+ * Extract translatable fields from frontmatter YAML.
+ * Supports dot notation for nested fields (e.g. "related.title").
+ * Returns a map of field path → value (only string fields).
+ */
+declare function extractTranslatableFields(frontmatterText: string): Record<string, string>;
+/**
+ * Reconstruct frontmatter with translated fields.
+ * Supports dot notation for nested fields.
+ * Preserves all non-translated fields and YAML formatting.
+ */
+declare function reconstructFrontmatter(frontmatterText: string, translatedFields: Record<string, string>): string;
+
+/**
+ * Preprocess MDX content to ensure JSX tags (<AppOnly>, <PagesOnly>, <details>, <div>)
+ * are separated from surrounding content by blank lines.
+ * This ensures remark parses them as independent HTML nodes,
+ * not merged with adjacent text content.
+ */
+declare function normalize(content: string): string;
+
+export { type DocsI18nConfig, type ProjectConfig, TranslationCache, assemble, defineConfig, extractTranslatableFields, flattenSources, loadConfig, normalize, parseMdx, reconstructFrontmatter };