transduck 0.2.5 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 AI-powered translation for apps and websites. Fast. Cheap. No keys to manage.
 
-TransDuck translates your app's strings using AI, then caches them locally in DuckDB so you never pay for the same translation twice. No translation files. No key naming. No sync headaches.
+TransDuck translates your app's strings using AI, then caches them locally in LMDB so you never pay for the same translation twice. No translation files. No key naming. No sync headaches.
 
 ```typescript
 import { initialize, setLanguage, ait, aitPlural } from 'transduck';
@@ -19,7 +19,7 @@ await aitPlural('{count} night', '{count} nights', 7);   // → "7 Nächte"
 
 - **No keys to manage** — your source text is the key
 - **No translation files** — translations live in a single in-memory database file
-- **Translate once, pay once** — cached lookups take ~1.5ms, zero API costs after first call
+- **Translate once, pay once** — cached lookups take ~0.015ms, zero API costs after first call
 - **AI that understands context** — project and per-string context for accurate translations
 - **Pluralization that works everywhere** — handles Russian (4 forms), Arabic (6 forms) automatically
 - **Built for vibe coding** — AI coding tools read the docs and wrap strings with `ait()` across your project
@@ -80,7 +80,7 @@ transduck stats                           # check your translation database
 pip install transduck
 ```
 
-Works with Django, Flask, FastAPI, and Jinja. Same DuckDB database format — share translations between Python and JS.
+Works with Django, Flask, FastAPI, and Jinja. Same LMDB database format — share translations between Python and JS.
 
 ## Links
 

package/dist/cli.js

@@ -18,7 +18,7 @@ export async function runInit(opts) {
     const config = {
         project: { name: opts.name, context: opts.context },
         languages: { source: opts.sourceLang.toUpperCase(), targets: opts.targetLangs.map(l => l.toUpperCase()) },
-        storage: { path: './translations.duckdb' },
+        storage: { path: './translations.lmdb' },
     };
     if (providerChoice === 2) {
         config.backend = {
@@ -46,7 +46,7 @@ export async function runInit(opts) {
     }
     const configPath = join(opts.dir, 'transduck.yaml');
     writeFileSync(configPath, yamlStringify(config));
-    const dbPath = join(opts.dir, 'translations.duckdb');
+    const dbPath = join(opts.dir, 'translations.lmdb');
     const store = new TranslationStore(dbPath);
     await store.initialize();
     store.close();
@@ -454,7 +454,7 @@ export async function runStats(opts) {
 }
 // CLI entry point
 const program = new Command();
-program.name('transduck').description('AI-native translation tool').version('0.2.5');
+program.name('transduck').description('AI-native translation tool').version('0.4.0');
 program.command('init')
     .description('Initialize a new transduck project')
     .action(async () => {

package/dist/react/index.d.ts

@@ -1 +1,2 @@
-export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from './provider.js';
+export type { UseTransDuckReturn } from './provider.js';

package/dist/react/index.js

@@ -1,2 +1,2 @@
 'use client';
-export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from './provider.js';

package/dist/react/provider.d.ts

@@ -1,10 +1,34 @@
 import { type ReactNode } from 'react';
+interface ReactState {
+    language: string;
+    sourceLang: string;
+    endpoint: string;
+    projectName: string;
+    cache: Map<string, string>;
+    pluralCache: Map<string, Record<string, string>>;
+    pendingStrings: Set<string>;
+    pendingPlurals: Set<string>;
+    knownKeys: Set<string>;
+    knownPlurals: Set<string>;
+    isLanguageSwitch: boolean;
+    triggerFetch: (() => void) | null;
+}
 /**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
+ * Hook that subscribes to translation updates and returns translation
+ * functions along with language state.
  */
-export declare function useTransDuck(): void;
+export interface UseTransDuckReturn {
+    t: typeof t;
+    tPlural: typeof tPlural;
+    ait: typeof t;
+    aitPlural: typeof tPlural;
+    language: string;
+    setLanguage: (lang: string) => void;
+    isLoading: boolean;
+}
+export declare function useTransDuck(): UseTransDuckReturn;
 export declare function _resetReactState(): void;
+export declare function _getReactState(): ReactState;
 export declare function t(sourceText: string, context?: string, vars?: Record<string, string | number>): string;
 export declare function tPlural(one: string, other: string, count: number, opts?: {
     context?: string;

package/dist/react/provider.js

@@ -1,39 +1,58 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useState, useCallback } from 'react';
+import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
 let _state = {
     language: '',
     sourceLang: 'EN',
     endpoint: '/api/translations',
+    projectName: 'default',
     cache: new Map(),
     pluralCache: new Map(),
     pendingStrings: new Set(),
     pendingPlurals: new Set(),
+    knownKeys: new Set(),
+    knownPlurals: new Set(),
+    isLanguageSwitch: false,
     triggerFetch: null,
 };
-// --- Context for triggering child re-renders ---
-// The context value (a version counter) changes when translations are loaded.
-// Components that call useTransDuck() subscribe to this and re-render automatically.
-const TransDuckContext = createContext(0);
-/**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
- */
+const defaultContext = {
+    version: 0,
+    language: '',
+    setLanguage: () => { },
+    isLoading: false,
+};
+const TransDuckContext = createContext(defaultContext);
 export function useTransDuck() {
-    useContext(TransDuckContext);
+    const ctx = useContext(TransDuckContext);
+    return {
+        t,
+        tPlural,
+        ait,
+        aitPlural,
+        language: ctx.language,
+        setLanguage: ctx.setLanguage,
+        isLoading: ctx.isLoading,
+    };
 }
 export function _resetReactState() {
     _state = {
         language: '',
         sourceLang: 'EN',
         endpoint: '/api/translations',
+        projectName: 'default',
         cache: new Map(),
         pluralCache: new Map(),
         pendingStrings: new Set(),
         pendingPlurals: new Set(),
+        knownKeys: new Set(),
+        knownPlurals: new Set(),
+        isLanguageSwitch: false,
         triggerFetch: null,
     };
 }
+export function _getReactState() {
+    return _state;
+}
 function interpolateVars(text, vars) {
     if (!vars)
         return text;
@@ -45,11 +64,12 @@ function interpolateVars(text, vars) {
 }
 // --- Stable exported functions ---
 export function t(sourceText, context, vars) {
+    const key = `${sourceText}||${context ?? ''}`;
+    _state.knownKeys.add(key);
     // Same language — return source
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
         return interpolateVars(sourceText, vars);
     }
-    const key = `${sourceText}||${context ?? ''}`;
     // Cache hit
     const cached = _state.cache.get(key);
     if (cached !== undefined) {
@@ -72,14 +92,15 @@ export function tPlural(one, other, count, opts) {
     else {
         vars = { ...opts.vars };
     }
+    const sourceKey = `${one}\x00${other}`;
+    const cacheKey = `${sourceKey}||${context ?? ''}`;
+    _state.knownPlurals.add(cacheKey);
     // Same language
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
         const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
         const form = rules.select(count) === 'one' ? one : other;
         return interpolateVars(form, vars);
     }
-    const sourceKey = `${one}\x00${other}`;
-    const cacheKey = `${sourceKey}||${context ?? ''}`;
     // Cache hit
     const cachedForms = _state.pluralCache.get(cacheKey);
     if (cachedForms) {
@@ -136,18 +157,52 @@ function saveToLocalStorage(projectName, language) {
 }
 export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/api/translations', projectName = 'default', children, }) {
     const [version, setVersion] = useState(0);
+    const [languageState, setLanguageState] = useState(language.toUpperCase());
+    const [isLoading, setIsLoading] = useState(false);
     // Update module-level state synchronously so t() works during first render
     _state.endpoint = endpoint;
     _state.sourceLang = sourceLang;
+    _state.projectName = projectName;
+    // Synchronous first-render initialization only.
+    // Subsequent language changes are handled by switchLanguage / useEffect prop sync.
     const upperLang = language.toUpperCase();
-    if (_state.language !== upperLang) {
+    if (!_state.language) {
         _state.language = upperLang;
-        _state.cache.clear();
-        _state.pluralCache.clear();
         loadFromLocalStorage(projectName, upperLang);
     }
+    const switchLanguage = useCallback((lang) => {
+        const upper = lang.toUpperCase();
+        // Same-language no-op
+        if (upper === _state.language)
+            return;
+        // Update React state
+        setLanguageState(upper);
+        // Update module-level state synchronously
+        _state.language = upper;
+        _state.cache.clear();
+        _state.pluralCache.clear();
+        // Source-language guard: skip fetch, t() short-circuits
+        if (upper === _state.sourceLang.toUpperCase()) {
+            setVersion(v => v + 1);
+            return;
+        }
+        // Load cached translations from localStorage
+        loadFromLocalStorage(_state.projectName, upper);
+        // Mark as language switch and re-queue known keys
+        _state.isLanguageSwitch = true;
+        setIsLoading(true);
+        for (const key of _state.knownKeys) {
+            _state.pendingStrings.add(key);
+        }
+        for (const key of _state.knownPlurals) {
+            _state.pendingPlurals.add(key);
+        }
+        // Bump version to trigger re-render and useEffect flush
+        setVersion(v => v + 1);
+    }, []);
     // Set up trigger
     const doFetch = useCallback(async () => {
+        const fetchLanguage = _state.language;
         const stringsToFetch = new Set(_state.pendingStrings);
         const pluralsToFetch = new Set(_state.pendingPlurals);
         _state.pendingStrings.clear();
@@ -161,8 +216,13 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
             if (_state.pluralCache.has(key))
                 pluralsToFetch.delete(key);
         }
-        if (stringsToFetch.size === 0 && pluralsToFetch.size === 0)
+        if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) {
+            if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+                _state.isLanguageSwitch = false;
+                setIsLoading(false);
+            }
             return;
+        }
         // Build request body
         const strings = Array.from(stringsToFetch).map(key => {
             const [text, context] = key.split('||');
@@ -188,6 +248,9 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
                 return;
             }
             const data = await response.json();
+            // Stale fetch protection: language changed while we were fetching
+            if (_state.language !== fetchLanguage)
+                return;
             // Store translations
             if (data.translations) {
                 for (const [key, value] of Object.entries(data.translations)) {
@@ -199,20 +262,41 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
                     _state.pluralCache.set(key, value);
                 }
             }
-            saveToLocalStorage(projectName, _state.language);
+            saveToLocalStorage(_state.projectName, _state.language);
             setVersion(v => v + 1);
         }
         catch (err) {
             console.warn('[transduck] Translation fetch error:', err);
         }
-    }, [endpoint, projectName]);
+        finally {
+            if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+                _state.isLanguageSwitch = false;
+                setIsLoading(false);
+            }
+        }
+    }, [endpoint]);
     // Register trigger
     _state.triggerFetch = doFetch;
+    // Sync language prop changes — only when the prop itself changes
+    const prevPropRef = React.useRef(upperLang);
+    useEffect(() => {
+        const upper = language.toUpperCase();
+        if (upper !== prevPropRef.current) {
+            prevPropRef.current = upper;
+            switchLanguage(upper);
+        }
+    }, [language, switchLanguage]);
     // Flush pending after render
     useEffect(() => {
         if (_state.pendingStrings.size > 0 || _state.pendingPlurals.size > 0) {
             doFetch();
         }
     });
-    return (_jsx(TransDuckContext.Provider, { value: version, children: children }));
+    const contextValue = {
+        version,
+        language: languageState,
+        setLanguage: switchLanguage,
+        isLoading,
+    };
+    return (_jsx(TransDuckContext.Provider, { value: contextValue, children: children }));
 }

package/dist/storage.d.ts

@@ -23,18 +23,23 @@ interface Stats {
 }
 export declare class TranslationStore {
     private dbPath;
-    private instance;
-    private conn;
+    private db;
     constructor(dbPath: string);
-    private getConn;
-    private convertRow;
-    query(sql: string, params?: string[]): Promise<Record<string, unknown>[]>;
     initialize(): Promise<void>;
+    private getDb;
     lookup(params: LookupParams): Promise<string | null>;
     insert(params: InsertParams): Promise<void>;
     lookupPlural(params: LookupParams): Promise<Record<string, string>>;
     insertPlural(params: InsertPluralParams): Promise<void>;
     stats(): Promise<Stats>;
+    /**
+     * Count entries matching optional filters.
+     */
+    count(targetLang?: string, failedOnly?: boolean): number;
+    /**
+     * Delete entries matching optional filters. Returns count deleted.
+     */
+    clear(targetLang?: string, failedOnly?: boolean): Promise<number>;
     close(): void;
 }
 export {};