locai 2.6.1 → 2.7.0

package/dist/services/source-analyzer.js

@@ -1,6 +1,22 @@
-import { Project, Node } from "ts-morph";
+import { Project, Node, ts, } from "ts-morph";
 import { log } from "../utils/logger.js";
 import path from "path";
+/** Longest usage snippet kept for a key, in characters. */
+const MAX_SNIPPET_LENGTH = 200;
+/** Source spans wider than this cannot shrink to a snippet, so they are not printed. */
+const MAX_SNIPPET_SOURCE_WIDTH = 10 * MAX_SNIPPET_LENGTH;
+/** Tooling directives (`eslint-disable-next-line`, `@ts-expect-error`, ...) say nothing about the text. */
+const DIRECTIVE_COMMENT = /^(eslint-|@ts-|prettier-ignore\b|istanbul ignore\b|c8 ignore\b|biome-ignore\b)/;
+/** Prints code without comments, for the usage snippet. */
+const printer = ts.createPrinter({ removeComments: true });
+/** Comment text without its markers (`//`, `/*`, `*\/`, JSDoc `*`), on one line. */
+const commentText = (comment) => comment
+    .replace(/^\/\/+|^\/\*+|\*+\/$/g, "")
+    .replace(/^\s*\*+/gm, "")
+    .replace(/\s+/g, " ")
+    .trim();
+/** Functions and methods: code in them runs later, not where they are written. */
+const isFunction = (node) => Node.isFunctionLikeDeclaration(node) || Node.isFunctionExpression(node);
 export class SourceCodeAnalyzer {
     project;
     keyUsageMap = new Map();
@@ -39,7 +55,8 @@ export class SourceCodeAnalyzer {
                 log(`Source analysis complete. Context extracted for ${this.keyUsageMap.size} keys.`);
             }
             catch (error) {
-                console.warn(`Error during source analysis: ${error.message}`);
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`Error during source analysis: ${message}`);
                 // Don't throw to prevent blocking the whole app, just log
             }
         })();
@@ -75,75 +92,32 @@ export class SourceCodeAnalyzer {
         }
     }
     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 component = this.findComponent(node);
+        const comments = this.getComments(node, component?.declaration);
+        // Props of the JSX element the text belongs to
         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;
+        this.findJsxElement(node)
+            ?.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);
                 }
-            });
-        }
-        // 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();
+                props[name] = value;
+            }
+        });
         const context = {
-            filePath: relativePath,
-            line,
-            component: componentName,
-            usageSnippet: snippet.length > 200 ? snippet.substring(0, 200) + "..." : snippet,
+            filePath: path.relative(this.rootDir, fullFilePath),
+            line: node.getStartLineNumber(),
+            component: component?.name,
+            usageSnippet: this.getSnippet(node),
             comments: comments.length > 0 ? comments : undefined,
             props: Object.keys(props).length > 0 ? props : undefined,
         };
@@ -152,6 +126,125 @@ export class SourceCodeAnalyzer {
         }
         this.keyUsageMap.get(key)?.push(context);
     }
+    /**
+     * The component the call is in: the nearest enclosing function, class or function-valued
+     * variable whose name starts with an uppercase letter, otherwise the nearest one of any name.
+     * A variable counts only when the call is inside a function in its initializer
+     * (`const Dialog = () => ...`), so `const label = t("key")` does not name a component.
+     */
+    findComponent(node) {
+        let nearest;
+        let insideFunction = false;
+        for (const ancestor of node.getAncestors()) {
+            let found;
+            if (Node.isFunctionDeclaration(ancestor) ||
+                Node.isFunctionExpression(ancestor) ||
+                Node.isClassDeclaration(ancestor)) {
+                const name = ancestor.getName();
+                if (name)
+                    found = { name, declaration: ancestor };
+            }
+            else if (insideFunction &&
+                Node.isVariableDeclaration(ancestor) &&
+                Node.isIdentifier(ancestor.getNameNode())) {
+                found = {
+                    name: ancestor.getName(),
+                    declaration: ancestor.getVariableStatement() ?? ancestor,
+                };
+            }
+            insideFunction ||= isFunction(ancestor);
+            if (found && /^[A-Z]/.test(found.name))
+                return found;
+            nearest ??= found;
+        }
+        return nearest;
+    }
+    /**
+     * The JSX element the text belongs to: the one whose attribute holds the call
+     * (`<Button title={t("key")} />`) or whose child it is (`<Button>{t("key")}</Button>`).
+     * A call inside a nested function (`onClick={() => alert(t("key"))}`) belongs to none.
+     */
+    findJsxElement(node) {
+        for (const ancestor of node.getAncestors()) {
+            if (Node.isJsxOpeningElement(ancestor) || Node.isJsxSelfClosingElement(ancestor)) {
+                return ancestor;
+            }
+            if (Node.isJsxElement(ancestor))
+                return ancestor.getOpeningElement();
+            if (Node.isJsxFragment(ancestor) ||
+                Node.isStatement(ancestor) ||
+                isFunction(ancestor)) {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Comments about the call, nearest first: comments right above the call's expression, JSX
+     * attribute, JSX element or statement, `{/* ... *\/}` comments right before its JSX element,
+     * and the comment above its component. Tooling directives are left out.
+     */
+    getComments(node, component) {
+        // Raw comments by start position; nested nodes share their leading comments
+        const found = new Map();
+        for (let current = node; current && !Node.isSourceFile(current); current = current.getParent()) {
+            for (const range of current.getLeadingCommentRanges()) {
+                found.set(range.getPos(), range.getText());
+            }
+            const parent = current.getParent();
+            if (Node.isJsxElement(parent) || Node.isJsxFragment(parent)) {
+                // `{/* ... */}` children right before this one. Compiler nodes, so a long list
+                // of children is not wrapped again for every call in it.
+                const sourceFile = current.getSourceFile().compilerNode;
+                const siblings = parent.compilerNode.children;
+                const self = current.compilerNode;
+                for (let i = siblings.findIndex((child) => child === self) - 1; i >= 0; i--) {
+                    const sibling = siblings[i];
+                    if (ts.isJsxText(sibling) && sibling.containsOnlyTriviaWhiteSpaces)
+                        continue;
+                    if (!ts.isJsxExpression(sibling) || sibling.expression)
+                        break;
+                    const text = sibling.getText(sourceFile);
+                    for (const match of text.matchAll(/\/\*[\s\S]*?\*\/|\/\/.*/g)) {
+                        found.set(sibling.getStart(sourceFile) + match.index, match[0]);
+                    }
+                }
+            }
+            if (Node.isStatement(current))
+                break;
+        }
+        for (const range of component?.getLeadingCommentRanges() ?? []) {
+            found.set(range.getPos(), range.getText());
+        }
+        return [...found.values()]
+            .map(commentText)
+            .filter((text) => text && !DIRECTIVE_COMMENT.test(text));
+    }
+    /**
+     * The code around the call with comments removed: the largest of the call, its enclosing
+     * expressions and its statement that fits in MAX_SNIPPET_LENGTH characters.
+     */
+    getSnippet(node) {
+        const print = (target) => printer
+            .printNode(ts.EmitHint.Unspecified, target.compilerNode, target.getSourceFile().compilerNode)
+            .replace(/\s+/g, " ")
+            .trim();
+        let snippet = print(node);
+        for (const ancestor of node.getAncestors()) {
+            if (Node.isSourceFile(ancestor) || ancestor.getWidth() > MAX_SNIPPET_SOURCE_WIDTH) {
+                break;
+            }
+            const text = print(ancestor);
+            if (text.length > MAX_SNIPPET_LENGTH)
+                break;
+            snippet = text;
+            if (Node.isStatement(ancestor))
+                break;
+        }
+        return snippet.length > MAX_SNIPPET_LENGTH
+            ? `${snippet.substring(0, MAX_SNIPPET_LENGTH)}...`
+            : snippet;
+    }
     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.

package/dist/services/translation-service.d.ts

@@ -1,6 +1,14 @@
+import { FlatTranslations } from "../utils/object-transformer.js";
 import Orchestrator from "../core/orchestrator.js";
-import StateManager from "../utils/state-manager.js";
+import StateManager, { StateComparison } from "../utils/state-manager.js";
 import { TranslationOptions, GlobalStats, LanguageProcessResult } from "../types/index.js";
+/** Result of `locai fix` for one source file. */
+export interface FixSummary {
+    /** Translations with a length issue. */
+    issues: number;
+    /** Of those, how many were re-translated successfully. */
+    fixed: number;
+}
 /**
  * Service for handling file translation operations.
  * Orchestrates the translation process including state management,
@@ -26,47 +34,56 @@ declare class TranslationService {
     /**
      * Initialize translation state and sync analysis.
      * @param {string} resolvedFile - Path to resolved source file.
-     * @param {Record<string, any>} flattenedSource - Flattened source content.
+     * @param {FlatTranslations} flattenedSource - Flattened source content.
      * @param {TranslationOptions} options - Translation options.
      * @returns {Promise<Object>} - Initialized state components.
      */
-    initializeTranslationState(resolvedFile: string, flattenedSource: Record<string, any>, options: TranslationOptions): Promise<{
+    initializeTranslationState(resolvedFile: string, flattenedSource: FlatTranslations, options: TranslationOptions): Promise<{
         stateManager: StateManager;
         projectRoot: string;
+        previousState: Record<string, string>;
         currentState: Record<string, string>;
-        comparison: import("../utils/state-manager.js").StateComparison;
+        comparison: StateComparison;
     }>;
     /**
      * Process all target languages with concurrency.
      * @param {string} resolvedFile - Path to source file.
-     * @param {Record<string, any>} flattenedSource - Flattened source content.
+     * @param {FlatTranslations} flattenedSource - Flattened source content.
      * @param {TranslationOptions} options - Translation options.
      * @param {GlobalStats} globalStats - Global statistics object to update.
-     * @param {any} comparison - State comparison result.
+     * @param {StateComparison} comparison - State comparison result.
      */
-    processAllLanguages(resolvedFile: string, flattenedSource: Record<string, any>, options: TranslationOptions, globalStats: GlobalStats, comparison: any): Promise<void>;
+    processAllLanguages(resolvedFile: string, flattenedSource: FlatTranslations, options: TranslationOptions, globalStats: GlobalStats, comparison: StateComparison): Promise<void>;
     /**
      * Process a single language translation.
      * @param {string} targetLang - Target language code.
      * @param {string} sourceFile - Path to source file.
-     * @param {Record<string, any>} flattenedSource - Flattened source content.
+     * @param {FlatTranslations} flattenedSource - Flattened source content.
      * @param {Orchestrator} orchestrator - Orchestrator instance.
      * @param {TranslationOptions} options - Translation options.
      * @param {GlobalStats} globalStats - Global statistics object.
-     * @param {any} comparison - State comparison result.
+     * @param {StateComparison} comparison - State comparison result.
      * @returns {Promise<LanguageProcessResult>} - Status and messages for this language.
      */
-    processLanguage(targetLang: string, sourceFile: string, flattenedSource: Record<string, any>, orchestrator: Orchestrator, options: TranslationOptions, globalStats: GlobalStats, comparison: any): Promise<LanguageProcessResult>;
+    processLanguage(targetLang: string, sourceFile: string, flattenedSource: FlatTranslations, orchestrator: Orchestrator, options: TranslationOptions, globalStats: GlobalStats, comparison: StateComparison): Promise<LanguageProcessResult>;
     /**
      * Finalize translation process and save state.
      * @param {StateManager} stateManager - State manager instance.
      * @param {string} projectRoot - Project root directory.
-     * @param {any} currentState - Current state object.
+     * @param {Record<string, string>} previousState - State loaded at the start of the run.
+     * @param {Record<string, string>} currentState - Current state (key → content hash).
+     * @param {StateComparison} comparison - New, modified and deleted keys of this run.
      * @param {GlobalStats} globalStats - Global statistics object.
      * @param {number} startTime - Process start timestamp.
      * @param {TranslationOptions} options - Translation options.
      */
-    finalizeTranslation(stateManager: StateManager, projectRoot: string, currentState: any, globalStats: GlobalStats, startTime: number, options: TranslationOptions): Promise<void>;
+    finalizeTranslation(stateManager: StateManager, projectRoot: string, previousState: Record<string, string>, currentState: Record<string, string>, comparison: StateComparison, globalStats: GlobalStats, startTime: number, options: TranslationOptions): Promise<void>;
+    /**
+     * Print the confidence scores of the run and, when the review queue is enabled, add the
+     * flagged translations to `.localize-cache/review-queue.json`.
+     * @param {Orchestrator[]} orchestrators - The run's orchestrators (they share the settings).
+     */
+    reportConfidence(orchestrators: Orchestrator[]): Promise<void>;
     /**
      * Remove deleted keys from all target language files.
      * @param {string} sourceFile - Path to source file.
@@ -78,9 +95,10 @@ declare class TranslationService {
      * Validate and fix existing translations that have length issues.
      * @param {string} file - Path to source file.
      * @param {TranslationOptions} options - Translation options.
+     * @returns {Promise<FixSummary>} - How many length issues were found and fixed.
      * @throws {Error} If validation process fails.
      */
-    validateAndFixExistingTranslations(file: string, options: TranslationOptions): Promise<void>;
+    validateAndFixExistingTranslations(file: string, options: TranslationOptions): Promise<FixSummary>;
     /**
      * Find locale files
      */