@saidksi/localizer-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,205 @@
+export type AIProvider = "anthropic" | "openai";
+export type KeyStyle = "dot.notation" | "snake_case";
+export type I18nLibrary = "react-i18next" | "next-intl" | "react-intl" | "vue-i18n" | "i18next";
+/**
+ * Shape of .localize.config.json in the user's project root.
+ * Loaded via cosmiconfig from `.localize.config.json` or the
+ * `localize` key in package.json.
+ */
+export interface LocalizeConfig {
+    /** ISO 639-1 code. Source of truth for key extraction. */
+    defaultLanguage: string;
+    /** Target translation languages, e.g. ["fr", "ar", "es"]. */
+    languages: string[];
+    /** Directory where messages/[lang]/*.json files are written. */
+    messagesDir: string;
+    /** Directories to scan, e.g. ["./src", "./app"]. */
+    include: string[];
+    /** Glob patterns to skip, e.g. ["node_modules", "dist", "**\/*.test.*"]. */
+    exclude: string[];
+    /** Which AI provider to use. */
+    aiProvider: AIProvider;
+    /** Specific model string, e.g. "claude-sonnet-4-6". */
+    aiModel: string;
+    /** Format for generated key names. */
+    keyStyle: KeyStyle;
+    /** Target i18n library — affects rewrite output. */
+    i18nLibrary: I18nLibrary;
+    /** If true, re-translate keys that already exist in target JSONs. */
+    overwriteExisting: boolean;
+    /** If true, `validate` exits with code 1 on any untranslated string. */
+    strictMode: boolean;
+    /**
+     * Enforced terminology per language.
+     * e.g. { "fr": { "Settings": "Paramètres" } }
+     */
+    glossary: Record<string, Record<string, string>>;
+    /** Additional glob patterns for strings to ignore during scanning. */
+    ignorePatterns?: string[];
+    /** File glob patterns to skip entirely, e.g. ["**\/*.stories.*"]. */
+    ignoreFiles?: string[];
+}
+export type NodeType = "JSXText" | "JSXAttribute" | "TemplateLiteral" | "StringLiteral" | "JSXInterpolation";
+/**
+ * A variable embedded in a JSXInterpolation string.
+ * e.g. "You have {{taskCount}} pending tasks" → { placeholder: "taskCount", expression: "taskCount" }
+ */
+export interface InterpolationVar {
+    /** The placeholder name used inside {{...}} in the template */
+    placeholder: string;
+    /** The raw JSX expression source: "taskCount", "user.name", etc. */
+    expression: string;
+}
+/**
+ * A single hardcoded string detected by the scanner.
+ * Carries enough context for the rewriter to locate and replace it.
+ */
+export interface ScanResult {
+    /** Absolute path to the source file. */
+    file: string;
+    /** 1-based line number of the string in the source file. */
+    line: number;
+    /** 0-based column of the string start. */
+    column: number;
+    /** The raw string value, e.g. "Welcome back". */
+    value: string;
+    /** AST node type — determines which transform the rewriter applies. */
+    nodeType: NodeType;
+    /** Human-readable context, e.g. "JSXText inside <h1>". */
+    context: string;
+    /** Up to 5 lines of surrounding source code for AI prompt context. */
+    surroundingCode: string;
+    /** True if this string is already wrapped in a t() / i18n.t() call. */
+    alreadyTranslated: boolean;
+    /**
+     * True if this string is at module level (outside any function/component).
+     * Module-level strings cannot use t() — the hook is not available there.
+     * The rewriter skips these; they appear in scan/translate output only.
+     */
+    isModuleLevel: boolean;
+    /**
+     * Resolved i18n key after the AI step.
+     * null until translate has run.
+     */
+    resolvedKey: string | null;
+    /**
+     * For JSXInterpolation nodes — the variable substitutions in the template.
+     * e.g. "You have {{taskCount}} pending tasks" → [{ placeholder: "taskCount", expression: "taskCount" }]
+     */
+    interpolations?: InterpolationVar[];
+    /**
+     * @internal Raw source text of all JSX children spanning this interpolation.
+     * Used by the rewriter to locate and replace the full span. Not shown in reports.
+     */
+    rawSpan?: string;
+    /**
+     * @internal For object property values, the name of the parent object variable.
+     * e.g. "statusConfig" for the "online" property in { online: "..." }
+     * Used to group related object properties as siblings.
+     */
+    objectKey?: string;
+}
+/** Full output of a scan command run. */
+export interface ScanReport {
+    generatedAt: string;
+    file?: string;
+    dir?: string;
+    results: ScanResult[];
+}
+/** Payload sent to an AI provider for a single unique string. */
+export interface AIRequest {
+    file: string;
+    componentContext: string;
+    element: string;
+    surroundingCode: string;
+    value: string;
+    keyStyle: KeyStyle;
+    /** Glossary entries relevant to this string, keyed by language. */
+    glossary: Record<string, string>;
+    targetLanguages: string[];
+    /**
+     * Other strings from the same component context (siblings).
+     * Used to hint at consistent key naming.
+     * e.g. ["Total views", "Total clicks", "Conversion rate"]
+     */
+    relatedStrings?: string[];
+    /**
+     * @internal Grouping key for finding siblings: "file:componentName"
+     * Not sent to AI, used internally for post-processing.
+     */
+    contextKey?: string;
+}
+/** Parsed response from an AI provider. */
+export interface AIResponse {
+    key: string;
+    /** Maps language code → translated string, e.g. { fr: "Se connecter" }. */
+    translations: Record<string, string>;
+}
+/** Outcome of rewriting a single source file. */
+export interface RewriteResult {
+    file: string;
+    /** Whether the user confirmed and the file was actually written. */
+    applied: boolean;
+    /** Number of strings replaced. */
+    changesCount: number;
+    /** Unified diff string shown to the user before confirmation. */
+    diff: string;
+    /** The full modified source — caller writes this to disk after confirmation. */
+    modifiedSource: string;
+}
+/** Coverage report for a single target language. */
+export interface ValidationResult {
+    language: string;
+    totalKeys: number;
+    presentKeys: number;
+    missingKeys: string[];
+    coveragePercent: number;
+}
+/** Single file record stored in .localize/cache.json. */
+export interface CacheEntry {
+    /** SHA-256 hex digest of the file contents at processing time. */
+    hash: string;
+    processedAt: string;
+    stringCount: number;
+}
+/** Full shape of .localize/cache.json. */
+export interface CacheStore {
+    version: 1;
+    /** Keyed by file path relative to the user's project root. */
+    entries: Record<string, CacheEntry>;
+}
+/** Options shared across all CLI commands. */
+export interface RunOptions {
+    file?: string;
+    dir?: string;
+    /** Target languages override, e.g. ["fr", "ar"]. */
+    lang?: string[];
+    dryRun?: boolean;
+    /** Skip confirmation prompts (apply all changes automatically). */
+    yes?: boolean;
+    /** Ignore cache and re-process all files. */
+    force?: boolean;
+    skipRewrite?: boolean;
+    skipValidate?: boolean;
+    /** Machine-readable mode — exits with code 1 on any failure. */
+    ci?: boolean;
+    /** Path to write a JSON report file. */
+    output?: string;
+}
+/** Summary returned after a full `localize run` pipeline. */
+export interface PipelineResult {
+    file?: string;
+    dir?: string;
+    /** Total strings detected by scanner. */
+    scanned: number;
+    /** Strings sent to AI and written to messages JSON. */
+    translated: number;
+    /** Source files rewritten. */
+    rewritten: number;
+    /** Whether the final validate step passed. */
+    validated: boolean;
+    durationMs: number;
+    /** Estimated USD cost of AI calls made during this run. */
+    aiCostUsd: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// ─── Config ──────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

package/dist/validator/index.d.ts

@@ -0,0 +1,65 @@
+import type { ValidationResult, LocalizeConfig, ScanResult } from "../types.js";
+/**
+ * Flatten a nested JSON object into dot-notation key paths.
+ *
+ * { auth: { sign_in: "Sign in", title: "Login" } }
+ * → ["auth.sign_in", "auth.title"]
+ *
+ * Exported for unit testing.
+ */
+export declare function flattenKeys(obj: Record<string, unknown>, prefix?: string): string[];
+/**
+ * Read all keys for a language by scanning every .json page file
+ * in `messagesDir/{lang}/`.
+ *
+ * Returns a Map of pageName → Set<dotNotationKey>.
+ */
+export declare function readLanguageKeys(messagesDir: string, lang: string): Promise<Map<string, Set<string>>>;
+export interface ValidateOptions {
+    /** Check only this language instead of all target languages */
+    lang?: string;
+    /**
+     * Restrict validation to a single page file derived from the source filename.
+     *
+     * Source file → page name → JSON file (all languages):
+     *   src/pages/Login.tsx    →  "login"  →  messages/{lang}/login.json
+     *   app/checkout/page.tsx  →  "page"   →  messages/{lang}/page.json
+     *
+     * Pass the page name (no extension), not the full source path.
+     * The CLI derives it via: basename(file, extname(file)).toLowerCase()
+     */
+    page?: string;
+}
+/**
+ * Validate key coverage across all target languages.
+ *
+ * Reads all messages/{lang}/*.json files and computes:
+ * - Which keys are present in the default language
+ * - Which of those keys are missing in each target language
+ * - Coverage percentage per language
+ *
+ * Always includes the default language in the result (always 100%).
+ */
+export declare function validateCoverage(config: LocalizeConfig, options?: ValidateOptions): Promise<ValidationResult[]>;
+/**
+ * Returns true if all target languages have 100% key coverage.
+ * Convenience wrapper used by `localize run` to decide the final status line.
+ */
+export declare function isFullyCovered(config: LocalizeConfig): Promise<boolean>;
+/**
+ * Populate `resolvedKey` on each ScanResult by looking up the string value
+ * in the default language messages JSON for that page.
+ *
+ * Called by `localize rewrite` when run standalone (after `localize translate`
+ * has already written the messages JSON).
+ *
+ * Results whose value cannot be found in the JSON are returned unchanged
+ * (resolvedKey stays null — they will be skipped by the rewriter).
+ */
+export declare function resolveKeysFromMessages(results: ScanResult[], config: LocalizeConfig): Promise<ScanResult[]>;
+/**
+ * Compute a diff of missing keys for a single language relative to the default.
+ * Used by `localize diff --lang ar`.
+ */
+export declare function getMissingKeys(config: LocalizeConfig, lang: string, page?: string): Promise<string[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/validator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIhF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,SAAK,GACV,MAAM,EAAE,CAeV;AAgCD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAenC;AA8CD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqD7B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAiCD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,UAAU,EAAE,CAAC,CAmCvB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAKnB"}

package/dist/validator/index.js

@@ -0,0 +1,237 @@
+import { readFile, readdir } from "fs/promises";
+import { resolve, join, basename, extname } from "path";
+// ─── Key flattening ───────────────────────────────────────────────────────────
+/**
+ * Flatten a nested JSON object into dot-notation key paths.
+ *
+ * { auth: { sign_in: "Sign in", title: "Login" } }
+ * → ["auth.sign_in", "auth.title"]
+ *
+ * Exported for unit testing.
+ */
+export function flattenKeys(obj, prefix = "") {
+    const keys = [];
+    for (const [k, v] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${k}` : k;
+        if (typeof v === "object" &&
+            v !== null &&
+            !Array.isArray(v)) {
+            keys.push(...flattenKeys(v, fullKey));
+        }
+        else {
+            keys.push(fullKey);
+        }
+    }
+    return keys;
+}
+// ─── Messages file reading ────────────────────────────────────────────────────
+/**
+ * Read and parse a single messages JSON file.
+ * Returns an empty object if the file doesn't exist or is invalid JSON.
+ */
+async function readMessagesFile(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * List all .json filenames inside a language directory.
+ * Returns [] if the directory doesn't exist.
+ */
+async function listPageFiles(langDir) {
+    try {
+        const entries = await readdir(langDir);
+        return entries.filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read all keys for a language by scanning every .json page file
+ * in `messagesDir/{lang}/`.
+ *
+ * Returns a Map of pageName → Set<dotNotationKey>.
+ */
+export async function readLanguageKeys(messagesDir, lang) {
+    const langDir = join(resolve(messagesDir), lang);
+    const pageFiles = await listPageFiles(langDir);
+    const result = new Map();
+    await Promise.all(pageFiles.map(async (filename) => {
+        const pageName = basename(filename, extname(filename));
+        const filePath = join(langDir, filename);
+        const json = await readMessagesFile(filePath);
+        result.set(pageName, new Set(flattenKeys(json)));
+    }));
+    return result;
+}
+/**
+ * Merge all per-page key sets into a single flat Set<string>.
+ * Used when validating total coverage without caring about pages.
+ */
+function mergeKeyMaps(pageKeys) {
+    const all = new Set();
+    for (const keys of pageKeys.values()) {
+        for (const k of keys)
+            all.add(k);
+    }
+    return all;
+}
+// ─── Validation logic ─────────────────────────────────────────────────────────
+/**
+ * Compute validation result for a single target language.
+ * Compares its keys against the default language's keys.
+ */
+function computeValidationResult(lang, defaultKeys, langKeys) {
+    const missingKeys = [];
+    for (const key of defaultKeys) {
+        if (!langKeys.has(key))
+            missingKeys.push(key);
+    }
+    const totalKeys = defaultKeys.size;
+    const presentKeys = totalKeys - missingKeys.length;
+    const coveragePercent = totalKeys === 0 ? 100 : Math.round((presentKeys / totalKeys) * 100);
+    return {
+        language: lang,
+        totalKeys,
+        presentKeys,
+        missingKeys,
+        coveragePercent,
+    };
+}
+/**
+ * Validate key coverage across all target languages.
+ *
+ * Reads all messages/{lang}/*.json files and computes:
+ * - Which keys are present in the default language
+ * - Which of those keys are missing in each target language
+ * - Coverage percentage per language
+ *
+ * Always includes the default language in the result (always 100%).
+ */
+export async function validateCoverage(config, options = {}) {
+    const { messagesDir, defaultLanguage, languages } = config;
+    // Read default language keys
+    const defaultPageKeys = await readLanguageKeys(messagesDir, defaultLanguage);
+    // If scoped to a specific page, narrow both sides
+    const effectiveDefaultKeys = options.page
+        ? (defaultPageKeys.get(options.page) ?? new Set())
+        : mergeKeyMaps(defaultPageKeys);
+    // Determine which languages to check
+    const targetLanguages = options.lang
+        ? languages.filter((l) => l === options.lang)
+        : languages;
+    const results = [];
+    // Default language is always 100% — include it first
+    results.push({
+        language: defaultLanguage,
+        totalKeys: effectiveDefaultKeys.size,
+        presentKeys: effectiveDefaultKeys.size,
+        missingKeys: [],
+        coveragePercent: 100,
+    });
+    // Check each target language
+    await Promise.all(targetLanguages.map(async (lang) => {
+        if (lang === defaultLanguage)
+            return; // already added above
+        const langPageKeys = await readLanguageKeys(messagesDir, lang);
+        const effectiveLangKeys = options.page
+            ? (langPageKeys.get(options.page) ?? new Set())
+            : mergeKeyMaps(langPageKeys);
+        results.push(computeValidationResult(lang, effectiveDefaultKeys, effectiveLangKeys));
+    }));
+    // Sort: default language first, then alphabetical
+    return results.sort((a, b) => {
+        if (a.language === defaultLanguage)
+            return -1;
+        if (b.language === defaultLanguage)
+            return 1;
+        return a.language.localeCompare(b.language);
+    });
+}
+/**
+ * Returns true if all target languages have 100% key coverage.
+ * Convenience wrapper used by `localize run` to decide the final status line.
+ */
+export async function isFullyCovered(config) {
+    const results = await validateCoverage(config);
+    return results.every((r) => r.coveragePercent === 100);
+}
+// ─── Key resolution (used by rewrite command) ─────────────────────────────────
+/**
+ * Flatten a nested JSON object to a value→key reverse-lookup map.
+ * Used to recover resolvedKey from messages JSON when rewrite runs standalone.
+ *
+ * { auth: { sign_in: "Sign in" } } → Map { "Sign in" → "auth.sign_in" }
+ *
+ * Note: if multiple keys have the same value, the last one wins.
+ */
+function buildValueToKeyMap(obj, prefix = "") {
+    const map = new Map();
+    for (const [k, v] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${k}` : k;
+        if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+            for (const [val, key] of buildValueToKeyMap(v, fullKey)) {
+                map.set(val, key);
+            }
+        }
+        else if (typeof v === "string") {
+            map.set(v, fullKey);
+        }
+    }
+    return map;
+}
+/**
+ * Populate `resolvedKey` on each ScanResult by looking up the string value
+ * in the default language messages JSON for that page.
+ *
+ * Called by `localize rewrite` when run standalone (after `localize translate`
+ * has already written the messages JSON).
+ *
+ * Results whose value cannot be found in the JSON are returned unchanged
+ * (resolvedKey stays null — they will be skipped by the rewriter).
+ */
+export async function resolveKeysFromMessages(results, config) {
+    // Build a cache of page → value→key map to avoid re-reading files
+    const pageCache = new Map();
+    async function getValueToKey(pageName) {
+        if (pageCache.has(pageName))
+            return pageCache.get(pageName);
+        const filePath = join(resolve(config.messagesDir), config.defaultLanguage, `${pageName}.json`);
+        try {
+            const content = await readFile(filePath, "utf-8");
+            const map = buildValueToKeyMap(JSON.parse(content));
+            pageCache.set(pageName, map);
+            return map;
+        }
+        catch {
+            const empty = new Map();
+            pageCache.set(pageName, empty);
+            return empty;
+        }
+    }
+    return Promise.all(results.map(async (r) => {
+        if (r.resolvedKey !== null)
+            return r; // already resolved
+        const pageName = basename(r.file, extname(r.file)).toLowerCase();
+        const valueToKey = await getValueToKey(pageName);
+        const key = valueToKey.get(r.value) ?? null;
+        return { ...r, resolvedKey: key };
+    }));
+}
+/**
+ * Compute a diff of missing keys for a single language relative to the default.
+ * Used by `localize diff --lang ar`.
+ */
+export async function getMissingKeys(config, lang, page) {
+    const options = { lang };
+    if (page)
+        options.page = page;
+    const results = await validateCoverage(config, options);
+    return results.find((r) => r.language === lang)?.missingKeys ?? [];
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@saidksi/localizer-core",
+  "version": "0.1.0",
+  "description": "Core i18n automation library for localizer",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./types": "./dist/types.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "localization",
+    "ast",
+    "code-generation",
+    "typescript"
+  ],
+  "author": "SaidKSI",
+  "license": "MIT",
+  "packageManager": "pnpm@10.33.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SaidKSI/localize-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SaidKSI/localize-core/issues"
+  },
+  "homepage": "https://github.com/SaidKSI/localize-core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/traverse": "^7.25.0",
+    "@babel/types": "^7.25.0",
+    "fast-glob": "^3.3.2",
+    "openai": "^4.65.0",
+    "p-limit": "^6.1.0",
+    "ts-morph": "^23.0.0",
+    "typescript": "^5.5.0"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.6",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=8.0.0"
+  }
+}