locai 2.4.0 → 2.5.0

package/README.md

@@ -13,6 +13,8 @@ Translate your project in seconds without installing anything:
 npx locai translate --source en --targets tr,es,de
 ```
 
+> **Need a permanent setup?** Check out our [Configuration Guide](./docs/configuration.md) to create a `localize.config.js` file.
+
 ## 📖 Documentation
 
 Everything you need to know to master Locai.
@@ -37,7 +39,9 @@ Choose the right brain for your localization. Compare OpenAI, Gemini, DeepSeek,
 
 Deep dive into Locai's intelligent features. We didn't just wrap an API; we built a localization engine.
 
-- **Infinite Memory**: Vector-based caching. We "remember" every translation. If you translate the same (or similar) sentence again, we fetch it from local cache instantly. Zero cost, 100% consistency.
+- **🧠 Smart Context Awareness**: Uses AI to understand the context of your strings for better translations.
+- **🔬 Deep Context Analysis**: Scans your source code (AST) to extract component names, comments, and props for context-aware translations.
+- **📚 Infinite Memory**: Uses vector embeddings to remember previous translations and maintain consistency. If you translate the same (or similar) sentence again, we fetch it from local cache instantly. Zero cost, 100% consistency.
 - **Smart Sync**: We hash every key. Locai only translates **new** or **modified** keys. If you have 1000 keys and change 5, we only send 5 to the AI.
 - **Context Awareness**: Locai analyzes your content. It knows if a string is for a **Button** (keep it short), **Marketing** (make it punchy), or **Legal** (be precise).
 - **Glossary & Brand Safety**: Define immutable terms (like "Locai", "API", "SaaS"). We guarantee they are never translated or corrupted.

package/dist/cli.js

@@ -26,6 +26,7 @@ const main = async () => {
         .option("-s, --source <lang>", "Source language", defaultConfig.source)
         .option("-t, --targets <langs>", "Target languages (comma separated)", (val) => val.split(","), defaultConfig.targets)
         .option("--localesDir <dir>", "Localization files directory", defaultConfig.localesDir)
+        .option("--no-deep-context", "Disable deep context analysis (source code scanning)")
         .option("--debug", "Enable debug mode with verbose logging", false)
         .option("--verbose", "Enable detailed diagnostic output", false);
     program.on("option:debug", function () {

package/dist/config/index.d.ts

@@ -9,6 +9,12 @@ export interface LocalizeConfig extends Omit<Partial<OrchestratorOptions>, "cont
      * Target language codes (e.g. ['tr', 'es'])
      */
     targets?: string[];
+    /**
+     * Deep Context (Source Code Analysis)
+     * Scans source code for context (component name, comments, props)
+     * @default true
+     */
+    deepContext?: boolean;
     /**
      * Filter by file extensions (e.g. ['.json', '.arb'])
      */

package/dist/core/orchestrator.d.ts

@@ -6,8 +6,10 @@ import GlossaryManager from "../utils/glossary-manager.js";
 import { TranslationResult } from "./pipeline/context.js";
 import { CacheStats } from "./pipeline/steps/CacheReadStep.js";
 import { ConfidenceSettings } from "./pipeline/steps/TranslationStep.js";
+import { SourceCodeAnalyzer } from "../services/source-analyzer.js";
 export interface OrchestratorOptions {
     context: ContextConfig;
+    deepContext?: boolean;
     progressOptions?: any;
     styleGuide?: any;
     lengthControl?: any;
@@ -78,6 +80,7 @@ declare class Orchestrator {
     vectorStore: VectorStore;
     embeddingProvider: EmbeddingProvider;
     vectorStats: VectorMemoryStats;
+    sourceAnalyzer: SourceCodeAnalyzer;
     confidenceSettings: ConfidenceSettings;
     private concurrencyLimit;
     private pipeline;

package/dist/core/orchestrator.js

@@ -22,6 +22,8 @@ import QualityCheckStep from "./pipeline/steps/QualityCheckStep.js";
 import ToneCheckStep from "./pipeline/steps/ToneCheckStep.js";
 import ConfidenceCheckStep from "./pipeline/steps/ConfidenceCheckStep.js";
 import CacheWriteStep from "./pipeline/steps/CacheWriteStep.js";
+import ContextEnrichmentStep from "./pipeline/steps/ContextEnrichmentStep.js";
+import { SourceCodeAnalyzer } from "../services/source-analyzer.js";
 // Vector Memory Imports
 import { VectorStore } from "../services/vector-store.js";
 import { EmbeddingProvider } from "../services/embedding-provider.js";
@@ -41,6 +43,8 @@ class Orchestrator {
     vectorStore;
     embeddingProvider;
     vectorStats;
+    // Source Code Analysis
+    sourceAnalyzer;
     confidenceSettings;
     concurrencyLimit;
     pipeline;
@@ -150,6 +154,26 @@ class Orchestrator {
                 }
             });
         }
+        // Initialize Source Analyzer
+        if (options.sourceCodeAnalyzer) {
+            this.sourceAnalyzer = options.sourceCodeAnalyzer;
+            // Assumed initialized or self-initializing
+        }
+        else {
+            this.sourceAnalyzer = new SourceCodeAnalyzer();
+            // Fire and forget initialization (or await if strict)
+            // We'll trust it catches up or is fast enough for the first few items,
+            // or we can await it if we want to block startup.
+            // For CLI responsiveness, we might want to await it only if deep context is enabled.
+            const deepContextEnabled = options.deepContext !== false; // Enabled by default
+            if (deepContextEnabled) {
+                this.sourceAnalyzer.initialize().catch((err) => {
+                    if (this.advanced.debug) {
+                        console.warn("Source analyzer init failed:", err.message);
+                    }
+                });
+            }
+        }
         // Initialize Pipeline
         this.pipeline = new Pipeline();
         this._buildPipeline();
@@ -182,6 +206,9 @@ class Orchestrator {
         // 3. Glossary Pre-processing
         this.pipeline.use(new GlossaryPreStep(this.glossaryManager));
         // 4. Translation
+        // 3.5 Context Enrichment (Deep Context)
+        const deepContextEnabled = this.options.deepContext !== false;
+        this.pipeline.use(new ContextEnrichmentStep(this.sourceAnalyzer, deepContextEnabled));
         this.pipeline.use(new TranslationStep(this.options, this.confidenceSettings));
         // 4.5 Vector Cache Write (save new translations)
         if (this.options.vectorMemory?.enabled) {

package/dist/core/pipeline/steps/ContextEnrichmentStep.d.ts

@@ -0,0 +1,9 @@
+import PipelineStep from "../PipelineStep.js";
+import { TranslationContext } from "../context.js";
+import { SourceCodeAnalyzer } from "../../../services/source-analyzer.js";
+export default class ContextEnrichmentStep extends PipelineStep {
+    private analyzer;
+    private enabled;
+    constructor(analyzer: SourceCodeAnalyzer, enabled?: boolean);
+    execute(context: TranslationContext, next: () => Promise<void>): Promise<void>;
+}

package/dist/core/pipeline/steps/ContextEnrichmentStep.js

@@ -0,0 +1,43 @@
+import PipelineStep from "../PipelineStep.js";
+export default class ContextEnrichmentStep extends PipelineStep {
+    analyzer;
+    enabled;
+    constructor(analyzer, enabled = true) {
+        super();
+        this.analyzer = analyzer;
+        this.enabled = enabled;
+    }
+    async execute(context, next) {
+        if (this.enabled) {
+            try {
+                // Ensure analysis is complete before checking for context
+                await this.analyzer.ensureInitialized();
+                const codeContext = this.analyzer.getContext(context.key);
+                if (codeContext) {
+                    // Enrich the context meta
+                    context.meta = {
+                        ...context.meta,
+                        code: codeContext,
+                    };
+                    // Also append to the AI prompt context if it exists
+                    // (Assuming existing translation prompt uses contextData)
+                    context.contextData = {
+                        ...(context.contextData || {}),
+                        visualContext: {
+                            component: codeContext.component,
+                            file: codeContext.filePath,
+                            comments: codeContext.comments,
+                            props: codeContext.props,
+                            snippet: codeContext.usageSnippet,
+                        },
+                    };
+                }
+            }
+            catch (error) {
+                // Non-blocking error
+                // console.warn(`Context enrichment failed for ${context.key}`, error);
+            }
+        }
+        await next();
+    }
+}

package/dist/services/source-analyzer.d.ts

@@ -0,0 +1,14 @@
+import { CodeContext } from "../types/context.js";
+export declare class SourceCodeAnalyzer {
+    private project;
+    private keyUsageMap;
+    private rootDir;
+    private initPromise;
+    constructor(rootDir?: string);
+    initialize(globPatterns?: string[]): Promise<void>;
+    ensureInitialized(): Promise<void>;
+    private processFile;
+    private processCallExpression;
+    private extractContext;
+    getContext(key: string): CodeContext | undefined;
+}

package/dist/services/source-analyzer.js

@@ -0,0 +1,164 @@
+import { Project, Node } from "ts-morph";
+import { log } from "../utils/logger.js";
+import path from "path";
+export class SourceCodeAnalyzer {
+    project;
+    keyUsageMap = new Map();
+    rootDir;
+    initPromise = null;
+    constructor(rootDir = process.cwd()) {
+        this.rootDir = rootDir;
+        // Initialize with default settings, but don't add files yet for performance
+        this.project = new Project({
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: {
+                allowJs: true,
+                jsx: 1, // Preserve
+            },
+        });
+    }
+    initialize(globPatterns = [
+        "src/**/*.{ts,tsx}",
+        "app/**/*.{ts,tsx}",
+        "components/**/*.{ts,tsx}",
+    ]) {
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0)); // Force async execution for race condition safety
+            try {
+                // Add source files
+                log(`Analyzing source code in ${this.rootDir}...`);
+                // Exclude node_modules explicitly just in case
+                this.project.addSourceFilesAtPaths(globPatterns);
+                const sourceFiles = this.project.getSourceFiles();
+                log(`Found ${sourceFiles.length} source files for context analysis.`);
+                for (const sourceFile of sourceFiles) {
+                    this.processFile(sourceFile);
+                }
+                log(`Source analysis complete. Context extracted for ${this.keyUsageMap.size} keys.`);
+            }
+            catch (error) {
+                console.warn(`Error during source analysis: ${error.message}`);
+                // Don't throw to prevent blocking the whole app, just log
+            }
+        })();
+        return this.initPromise;
+    }
+    async ensureInitialized() {
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+    }
+    processFile(sourceFile) {
+        sourceFile.forEachDescendant((node) => {
+            if (Node.isCallExpression(node)) {
+                this.processCallExpression(node, sourceFile.getFilePath());
+            }
+        });
+    }
+    processCallExpression(node, filePath) {
+        // Match t('key') or useTranslations().t('key') pattern
+        // This is a heuristic match
+        const expression = node.getExpression();
+        // Check if expression is accessible
+        if (!expression)
+            return;
+        const expressionText = expression.getText();
+        // Simple check for 't' function calls
+        if (expressionText.endsWith(".t") || expressionText === "t") {
+            const args = node.getArguments();
+            if (args.length > 0 && Node.isStringLiteral(args[0])) {
+                const key = args[0].getLiteralText();
+                this.extractContext(key, node, filePath);
+            }
+        }
+    }
+    extractContext(key, node, fullFilePath) {
+        const relativePath = path.relative(this.rootDir, fullFilePath);
+        const line = node.getStartLineNumber();
+        // Extract component name
+        let componentName = undefined;
+        // Use getAncestors() to find the parent safely
+        const componentNode = node
+            .getAncestors()
+            .find((n) => Node.isFunctionDeclaration(n) ||
+            Node.isClassDeclaration(n) ||
+            Node.isVariableDeclaration(n));
+        if (componentNode) {
+            if (Node.isFunctionDeclaration(componentNode) ||
+                Node.isClassDeclaration(componentNode)) {
+                componentName = componentNode.getName();
+            }
+            else if (Node.isVariableDeclaration(componentNode)) {
+                componentName = componentNode.getName();
+            }
+        }
+        // Extract comments
+        // Look for leading comments on the statement
+        const statement = node
+            .getAncestors()
+            .find((n) => Node.isExpressionStatement(n) ||
+            Node.isVariableStatement(n) ||
+            Node.isJsxElement(n) ||
+            Node.isJsxExpression(n));
+        const comments = [];
+        const targetNode = statement || node;
+        const ranges = targetNode.getLeadingCommentRanges();
+        for (const range of ranges) {
+            comments.push(range
+                .getText()
+                .replace(/^\/\/\s*/, "")
+                .replace(/^\/\*\s*/, "")
+                .replace(/\s*\*\/$/, ""));
+        }
+        // Get props (simple heuristic for JSX)
+        const props = {};
+        const jsxElement = node
+            .getAncestors()
+            .find((n) => Node.isJsxOpeningElement(n) || Node.isJsxSelfClosingElement(n));
+        if (jsxElement &&
+            (Node.isJsxOpeningElement(jsxElement) || Node.isJsxSelfClosingElement(jsxElement))) {
+            jsxElement.getAttributes().forEach((attr) => {
+                if (Node.isJsxAttribute(attr)) {
+                    // Safe name extraction
+                    const nameNode = attr.getNameNode();
+                    const name = nameNode ? nameNode.getText() : "unknown";
+                    const initializer = attr.getInitializer();
+                    let value = initializer ? initializer.getText() : "true";
+                    // Strip quotes if string literal
+                    if ((value.startsWith('"') && value.endsWith('"')) ||
+                        (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.substring(1, value.length - 1);
+                    }
+                    props[name] = value;
+                }
+            });
+        }
+        // Code Snippet (surrounding lines)
+        // Check for node.getParent() to avoid error if node is root (unlikely for call expression)
+        const parent = node.getParent();
+        const snippet = parent ? parent.getText() : node.getText();
+        const context = {
+            filePath: relativePath,
+            line,
+            component: componentName,
+            usageSnippet: snippet.length > 200 ? snippet.substring(0, 200) + "..." : snippet,
+            comments: comments.length > 0 ? comments : undefined,
+            props: Object.keys(props).length > 0 ? props : undefined,
+        };
+        if (!this.keyUsageMap.has(key)) {
+            this.keyUsageMap.set(key, []);
+        }
+        this.keyUsageMap.get(key)?.push(context);
+    }
+    getContext(key) {
+        // Return duplicate functionality: prefer the first usage found or merge?
+        // For now return the first usage that has comments, or just the first usage.
+        const usages = this.keyUsageMap.get(key);
+        if (!usages || usages.length === 0)
+            return undefined;
+        // Prioritize usage with comments
+        return usages.find((u) => u.comments && u.comments.length > 0) || usages[0];
+    }
+}

package/dist/services/translation-service.js

@@ -9,6 +9,7 @@ import gracefulShutdown from "../utils/graceful-shutdown.js";
 import uiManager from "../utils/ui-manager.js";
 import statisticsManager from "../utils/statistics-manager.js";
 import { LanguageProcessor } from "./language-processor.js";
+import { SourceCodeAnalyzer } from "./source-analyzer.js";
 /**
  * Service for handling file translation operations.
  * Orchestrates the translation process including state management,
@@ -151,6 +152,10 @@ class TranslationService {
         const languageConcurrency = options.concurrencyLimit || 3;
         const targetLanguages = [...(options.targets || [])];
         await uiManager.log(`Processing ${targetLanguages.length} languages with concurrency of ${languageConcurrency}`);
+        // Initialize shared SourceCodeAnalyzer
+        console.log("Initializing Locai Engine...");
+        const sharedAnalyzer = new SourceCodeAnalyzer();
+        sharedAnalyzer.initialize();
         // Create shared orchestrators array to collect review queues
         const orchestrators = [];
         for (let i = 0; i < targetLanguages.length; i += languageConcurrency) {
@@ -167,6 +172,7 @@ class TranslationService {
                     ...options,
                     concurrencyLimit: 1,
                     progressOptions,
+                    sourceCodeAnalyzer: sharedAnalyzer,
                 });
                 orchestrators.push(orchestrator);
                 return this.processLanguage(targetLang, resolvedFile, flattenedSource, orchestrator, { ...options, progressOptions }, globalStats, comparison);

package/dist/types/context.d.ts

@@ -0,0 +1,13 @@
+export interface CodeContext {
+    filePath: string;
+    line: number;
+    component?: string;
+    usageSnippet?: string;
+    comments?: string[];
+    props?: Record<string, string>;
+}
+export interface SourceAnalyzerConfig {
+    enabled?: boolean;
+    include?: string[];
+    exclude?: string[];
+}

package/dist/types/context.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "locai",
-	"version": "2.4.0",
+	"version": "2.5.0",
 	"type": "module",
 	"main": "dist/core/orchestrator.js",
 	"types": "dist/core/orchestrator.d.ts",
@@ -16,7 +16,7 @@
 		"start": "node dist/core/orchestrator.js",
 		"dev": "tsx src/core/orchestrator.js",
 		"build": "tsc",
-		"type-check": "tsc --noEmit",
+		"typecheck": "tsc --noEmit",
 		"lint": "eslint .",
 		"lint:fix": "eslint . --fix",
 		"format": "prettier --write \"**/*.{js,json,md,jsx,ts,tsx,css}\"",
@@ -72,8 +72,8 @@
 		"./translator": "./dist/commands/translator.js"
 	},
 	"dependencies": {
-		"axios": "1.13.1",
-		"c12": "^3.3.2",
+		"axios": "1.13.2",
+		"c12": "^3.3.3",
 		"commander": "^14.0.2",
 		"dot-properties": "^1.1.0",
 		"dotenv": "^17.2.3",
@@ -81,25 +81,26 @@
 		"gettext-parser": "^8.0.0",
 		"jiti": "^2.6.1",
 		"js-yaml": "^4.1.1",
-		"lru-cache": "^11.2.2",
+		"lru-cache": "^11.2.4",
 		"p-limit": "^7.2.0",
 		"prompts": "^2.4.2",
+		"ts-morph": "^27.0.2",
 		"vectra": "^0.11.1"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.39.1",
+		"@eslint/js": "^9.39.2",
 		"@types/js-yaml": "^4.0.9",
-		"@types/node": "^25.0.1",
+		"@types/node": "^25.0.3",
 		"@types/prompts": "^2.4.9",
-		"@vitest/coverage-v8": "^4.0.15",
-		"eslint": "^9.39.1",
+		"@vitest/coverage-v8": "^4.0.16",
+		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
 		"globals": "^16.5.0",
-		"prettier": "^3.6.2",
+		"prettier": "^3.7.4",
 		"std-mocks": "^2.0.0",
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.15"
+		"vitest": "^4.0.16"
 	},
 	"files": [
 		"dist/"