@babelize/engine 0.0.0-stage → 0.1.0

package/dist/runtime/types.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Engine v2 runtime types (backend-facing).
+ *
+ * This file intentionally keeps the operational contract that the backend
+ * workers/controllers already rely on (stats/locales/injections/diffs), while
+ * allowing the v2 engine to add richer metrics needed for Target.md.
+ */
+import type { ByokProvider, FormatLocaleConfig, Framework } from '@babelize/types';
+import type { EngineProviders, TranslationFailure } from '../providers/types';
+import type { EngineLogger } from '../utils/logger';
+export interface EngineConfigV2 {
+    /** Path to the workspace directory */
+    workspacePath: string;
+    /** Source input type */
+    inputType: 'github' | 'zip';
+    /** Source locale code (e.g., 'en') */
+    sourceLocale: string;
+    /** Target locale codes (e.g., ['fr', 'de', 'es']) */
+    targetLocales: string[];
+    /** Detected or specified framework */
+    framework?: Framework;
+    /** Minimum confidence level for AST injection (0-100) */
+    confidenceThreshold: number;
+    /** If true, don't write any files - just return what would be changed */
+    dryRun: boolean;
+    /** Force translation even if locale files exist */
+    forceTranslation?: boolean;
+    /** Project ID for scoping lockfile/memory */
+    projectId?: string;
+    /**
+     * Directory holding `.babelize/<projectId>/babelize-lock.json`. Default:
+     * $BABELIZE_DATA_DIR, else the process cwd (the cloud backend). Local runs
+     * pass their temp copy, so concurrent runs never share global state.
+     */
+    dataDir?: string;
+    /** Logger for this run only (default: the one set with setEngineLogger). */
+    logger?: EngineLogger;
+    /** Callback for progress updates */
+    onProgress?: (message: string, step?: string, status?: 'running' | 'success' | 'error' | 'warning') => void;
+    /**
+     * Infrastructure the engine uses (translator, translation memory, project
+     * glossary/brand voice, cache). Anything omitted is simply not used.
+     */
+    providers?: EngineProviders;
+    /** BYOK (Bring Your Own Key) translation provider config */
+    byok?: {
+        provider: ByokProvider;
+        apiKey: string;
+        /** Optional model override (used by OpenRouter, Groq, etc.) */
+        model?: string;
+    };
+    /**
+     * Run the package manager when finalization adds i18n dependencies to
+     * package.json. Default true; local CLI runs pass false and tell the user
+     * to install instead.
+     */
+    installDependencies?: boolean;
+    /** Optional: only scan and process these specific files (e.g. for sync-triggered runs) */
+    filesToProcess?: string[];
+    /** Format localization config. null/undefined = skip format localization entirely. */
+    formatConfig?: FormatLocaleConfig;
+    /**
+     * What the run's translator can do. `icu`: translate ICU plural messages
+     * (an LLM provider). Defaults to true with BYOK or an injected translator,
+     * false for the NLLB service — then JSX sentences keep a plain `{count}`.
+     */
+    capabilities?: {
+        icu?: boolean;
+    };
+    /** Static HTML runtime options */
+    staticRuntime?: {
+        injectSwitcher?: boolean;
+        wrapMixedContent?: boolean;
+    };
+}
+export interface WorkspaceInfo {
+    path: string;
+    framework: Framework;
+    sourceDirs: string[];
+    hasLocalesDir: boolean;
+    existingLocales: string[];
+    publicDir: string;
+    packageJson?: Record<string, any>;
+    /** Output locale file format (e.g., 'json' for React, 'po' for Django) */
+    localeFormat: 'json' | 'po' | 'arb';
+    /** Format localization config propagated from EngineConfigV2 */
+    formatConfig?: FormatLocaleConfig;
+    /** Static HTML runtime options propagated from EngineConfigV2 */
+    staticRuntime?: {
+        injectSwitcher?: boolean;
+        wrapMixedContent?: boolean;
+    };
+}
+/**
+ * Frameworks that the engine pipeline will actively process.
+ * Runtime detection may produce other identifiers (e.g. 'unknown');
+ * those are validated against this list and rejected if not supported.
+ *
+ * @deprecated Import SUPPORTED_FRAMEWORKS from @babelize/types instead
+ */
+export type FormatClass = 'currency' | 'date' | 'number' | 'unknown';
+export interface DetectedFormat {
+    class: FormatClass;
+    rawValue: string;
+    originalString: string;
+    confidence: number;
+    detectedCurrency?: string;
+    dateOptions?: Intl.DateTimeFormatOptions;
+    dateSource?: string;
+    numberOptions?: Intl.NumberFormatOptions;
+}
+export interface ExtractedString {
+    text: string;
+    file: string;
+    line: number;
+    column: number;
+    context: 'jsx-text' | 'jsx-attr' | 'string-literal' | 'template-literal' | 'hardcoded-date' | 'hardcoded-currency' | 'format-string';
+    id: string;
+    variables?: string[];
+    parentContext?: string;
+    siblingGroupId?: string;
+    detectedFormat?: DetectedFormat;
+    /**
+     * A whole JSX sentence (text + `{expressions}` + inline elements) as one ICU
+     * message with named placeholders, rich-text tags and possibly a plural.
+     * Keys are named from its words only, and the message carries its own
+     * plural forms (no `_one`/`_other` key variants).
+     */
+    icuMessage?: boolean;
+    /**
+     * Source offsets of every node this id stands for. Injection replaces
+     * exactly these nodes (not others with the same text on the same line).
+     */
+    offsets?: number[];
+}
+export interface ExtractionResult {
+    strings: ExtractedString[];
+    filesAnalyzed: string[];
+    skippedFiles: SkippedFile[];
+    warnings?: Warning[];
+    /** UI strings found but deliberately not extracted (e.g. module-level constants that are also data). */
+    notInjected?: NotInjectedString[];
+}
+export interface GeneratedKey {
+    key: string;
+    namespace: string;
+    value: string;
+    extractionId: string;
+    isPlural?: boolean;
+    pluralCategory?: 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+    parentContext?: string;
+    extractionContext?: string;
+}
+export interface KeyGenerationResult {
+    keys: GeneratedKey[];
+    duplicates: Array<{
+        original: string;
+        renamed: string;
+    }>;
+}
+export interface LocaleData {
+    [key: string]: string | LocaleData;
+}
+export interface LocaleFile {
+    locale: string;
+    path: string;
+    data: LocaleData;
+    isNew: boolean;
+    isRTL?: boolean;
+}
+export interface LocaleHandlingResult {
+    sourceLocale: LocaleFile;
+    newKeysCount: number;
+    existingKeysCount: number;
+}
+export interface TranslationEntry {
+    key: string;
+    value: string;
+    confidence?: number;
+    engine?: string;
+    warnings?: string[];
+    parentContext?: string;
+    extractionContext?: string;
+}
+export interface TranslationRequest {
+    sourceLang: string;
+    targetLang: string;
+    entries: TranslationEntry[];
+}
+export interface TranslationResponse {
+    translations: TranslationEntry[];
+    metadata?: {
+        dictVersion?: string;
+        processingTimeMs?: number;
+        dictionaryHits?: number;
+        modelTranslations?: number;
+    };
+}
+export interface TranslationResult {
+    locales: LocaleFile[];
+    errors: Array<{
+        locale: string;
+        error: string;
+    }>;
+    /** Keys with no translation for a locale this run (not written, retried next run). */
+    failures?: TranslationFailure[];
+}
+export interface InjectionLocation {
+    file: string;
+    line: number;
+    column: number;
+    original: string;
+    replacement: string;
+    key: string;
+    confidence: number;
+    formatClass?: string;
+}
+export interface FileInjection {
+    file: string;
+    originalContent: string;
+    modifiedContent: string;
+    injections: InjectionLocation[];
+    importAdded: boolean;
+    hookAdded: boolean;
+}
+export interface InjectionResult {
+    modifiedFiles: FileInjection[];
+    skippedFiles: SkippedFile[];
+    totalInjections: number;
+}
+export interface SkippedFile {
+    file: string;
+    reason: 'syntax-error' | 'low-confidence' | 'already-translated' | 'binary' | 'excluded' | 'parse-error' | 'format-injection-failed' | 'format-ast-build-failed';
+    details?: string;
+}
+export interface Warning {
+    type: 'low-confidence' | 'duplicate-key' | 'complex-expression' | 'dynamic-string' | 'malformed-ast' | 'parse-warning' | 'hardcoded-currency' | 'hardcoded-date' | 'hardcoded-plural' | 'ambiguous-format' | 'overflow' | 'rtl';
+    file: string;
+    line?: number;
+    key?: string;
+    locale?: string;
+    severity?: 'warning' | 'critical';
+    dismissible?: boolean;
+    message: string;
+}
+export interface DiffMetadata {
+    file: string;
+    changeType: 'created' | 'modified';
+    linesAdded: number;
+    linesRemoved: number;
+    diff?: string;
+}
+export interface ProcessingStats {
+    filesScanned: number;
+    filesWithStrings: number;
+    stringsExtracted: number;
+    keysGenerated: number;
+    filesModified: number;
+    injectionsApplied: number;
+    localeFilesCreated: number;
+    processingTimeMs: number;
+    stringsNeedingTranslation?: number;
+    translationsFromMemory?: number;
+    translationsFromLockfile?: number;
+    translationsFromHF?: number;
+    /** True when engine ran with a project-scoped lockfile */
+    lockfileUsed?: boolean;
+    /** Keys sent to the translator (new + source-changed + missing locale) */
+    lockfileKeysTranslated?: number;
+    /** Keys whose source text changed vs the lockfile */
+    lockfileKeysChanged?: number;
+    /**
+     * (key, locale) translations the translator actually produced this run —
+     * the billable work. Excludes lockfile, translation-memory and cache reuse,
+     * and failed keys.
+     */
+    translatedThisRun?: number;
+}
+export interface NotInjectedString {
+    file: string;
+    key: string;
+    text: string;
+    reason: string;
+}
+export interface KeyUsageReport {
+    /**
+     * Source-locale keys that no code references any more (and weren't
+     * extracted this run). Not translated, not deleted.
+     */
+    unused: string[];
+    /**
+     * Files with translation calls whose key isn't a literal. When non-empty,
+     * every key is treated as live and `unused` is empty.
+     */
+    dynamicFiles: string[];
+}
+export interface EngineResultV2 {
+    success: boolean;
+    error?: string;
+    /**
+     * Keys that could not be translated, per locale, with the reason. They are
+     * absent from the locale files and the lockfile, so the next run retries
+     * them. Never filled with source text.
+     */
+    translationFailures?: TranslationFailure[];
+    stats: ProcessingStats;
+    locales: LocaleFile[];
+    injections: InjectionResult;
+    warnings: Warning[];
+    skipped: SkippedFile[];
+    diffs: DiffMetadata[];
+    /**
+     * Human-readable notes from finalization (dependencies added to
+     * package.json, i18n config created, ...) that need the user's attention.
+     */
+    notes?: string[];
+    /** Which source keys are still used (lockfile runs only). */
+    keyUsage?: KeyUsageReport;
+    /**
+     * Strings that were extracted and got a key (and translations) but could
+     * not be wired into the code, so the literal is still there.
+     */
+    notInjected?: NotInjectedString[];
+    results?: {
+        source: Record<string, string>;
+        targets: Record<string, Record<string, string>>;
+        metadata?: Record<string, Record<string, any>>;
+    };
+}
+export interface Phase0Result {
+    workspace: WorkspaceInfo;
+}
+export interface Phase1Result {
+    extraction: ExtractionResult;
+}
+export interface Phase2Result {
+    keyGeneration: KeyGenerationResult;
+}
+export interface Phase3Result {
+    localeHandling: LocaleHandlingResult;
+}
+export interface Phase4Result {
+    translation: TranslationResult;
+}
+export interface Phase5Result {
+    injection: InjectionResult;
+}
+export interface Phase6Result {
+    stats: ProcessingStats;
+    warnings: Warning[];
+    diffs: DiffMetadata[];
+}
+export interface Phase7Result {
+    finalization: {
+        dependenciesInvalid: boolean;
+        configFileCreated: boolean;
+        entryPointModified: boolean;
+        warnings: string[];
+    };
+}
+export declare const SUPPORTED_EXTENSIONS: string[];
+export declare const EXCLUDED_PATTERNS: string[];
+export declare const JSX_TRANSLATABLE_ATTRS: string[];

package/dist/runtime/types.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Engine v2 runtime types (backend-facing).
+ *
+ * This file intentionally keeps the operational contract that the backend
+ * workers/controllers already rely on (stats/locales/injections/diffs), while
+ * allowing the v2 engine to add richer metrics needed for Target.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSX_TRANSLATABLE_ATTRS = exports.EXCLUDED_PATTERNS = exports.SUPPORTED_EXTENSIONS = void 0;
+// ============ Constants ============
+exports.SUPPORTED_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.html'];
+exports.EXCLUDED_PATTERNS = [
+    'node_modules',
+    '.git',
+    '.next',
+    'dist',
+    'build',
+    'coverage',
+    '__tests__',
+    'vendor',
+    'lib',
+    'libs',
+    '*.test.*',
+    '*.spec.*',
+    '*.d.ts',
+    '*.min.js',
+    '*.min.css',
+];
+exports.JSX_TRANSLATABLE_ATTRS = [
+    'title',
+    'placeholder',
+    'alt',
+    'aria-label',
+    'aria-description',
+    'label',
+    'description',
+];

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+import type { z } from 'zod';
+import type { Framework } from '@babelize/types';
+export declare const ISO639_1_REGEX: RegExp;
+export interface BabelizeConfig {
+    /** Workspace path */
+    workspacePath: string;
+    /** Source locale (ISO 639-1) */
+    sourceLocale: string;
+    /** Target locales (ISO 639-1) */
+    targetLocales: string[];
+    /** Optional framework hint (otherwise auto-detected by extractor later) */
+    framework?: Framework;
+    /** If true, do not write files or open PRs */
+    dryRun?: boolean;
+    /** Project id (used for translation memory scoping) */
+    projectId?: string;
+    /** Optional path overrides */
+    sourceDir?: string;
+    localesDir?: string;
+    /** Glossary */
+    glossary?: GlossaryConfig;
+    /** Lockfile path */
+    lockfilePath?: string;
+}
+export type BabelizeConfigSchema = z.ZodType<BabelizeConfig>;
+export interface GlossaryConfig {
+    neverTranslate?: string[];
+    alwaysTranslateAs?: Array<{
+        term: string;
+        translations: Record<string, string>;
+    }>;
+}
+export type ExtractedStringContext = 'jsx-text' | 'jsx-attr' | 'string-literal' | 'template-literal' | 'hardcoded-date' | 'hardcoded-currency';
+export interface ExtractedString {
+    id: string;
+    text: string;
+    filePath: string;
+    line: number;
+    column: number;
+    context: ExtractedStringContext;
+}
+export interface TranslationUnit {
+    sourceText: string;
+    sourceLocale: string;
+    targetLocale: string;
+    /** Masked text sent to model (after glossary masking), if applicable */
+    maskedSourceText?: string;
+}
+export interface TranslationResult {
+    sourceText: string;
+    sourceLocale: string;
+    targetLocale: string;
+    translatedText: string;
+    /** "memory" | "hf" | "lockfile" */
+    provider: 'memory' | 'hf' | 'lockfile';
+    model?: string;
+}
+export interface BabelRunStats {
+    stringsExtracted: number;
+    stringsNeedingTranslation: number;
+    translationsFromMemory: number;
+    translationsFromLockfile: number;
+    translationsFromHF: number;
+}
+export interface BabelRunResult {
+    success: boolean;
+    error?: string;
+    stats: BabelRunStats;
+    warnings: any[];
+}
+export interface FileSystem {
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, contents: string): Promise<void>;
+    exists(filePath: string): Promise<boolean>;
+    listDir(dirPath: string): Promise<string[]>;
+    mkdir(dirPath: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+}
+export interface Cache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    invalidate(prefix: string): Promise<void>;
+}
+export interface GitHubProvider {
+    openPR(params: {
+        title: string;
+        body: string;
+        head: string;
+        base: string;
+    }): Promise<string>;
+}
+export interface TranslatorClient {
+    health(): Promise<boolean>;
+    warmup(): Promise<boolean>;
+    translate(req: HFTranslateRequest): Promise<HFTranslateResponse>;
+}
+export interface BabelizeEngineDependencies {
+    fs: FileSystem;
+    translatorClient: TranslatorClient;
+    cache?: Cache;
+    github?: GitHubProvider;
+}
+export interface HFTranslateRequest {
+    entries: Array<{
+        key: string;
+        value: string;
+        context?: string;
+        extractionContext?: string;
+    }>;
+    sourceLang: string;
+    targetLang: string;
+    /** Optional brand voice guideline for BYOK LLM providers */
+    brandVoice?: string;
+    /** Target locale as ISO code (keeps regional variants such as pt-BR). */
+    targetLocale?: string;
+    /** Required terminology: source term → translation. */
+    glossary?: Array<{
+        term: string;
+        translation: string;
+    }>;
+    /** Per-key notes for a repair attempt. */
+    hints?: Record<string, string>;
+}
+export interface HFTranslateResponse {
+    translations: Array<{
+        key?: string;
+        value: string;
+    }>;
+    model?: string;
+    metadata?: any;
+}
+export type { Phase7Result } from './runtime/types';
+export { SUPPORTED_EXTENSIONS, EXCLUDED_PATTERNS, JSX_TRANSLATABLE_ATTRS, } from './runtime/types';

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSX_TRANSLATABLE_ATTRS = exports.EXCLUDED_PATTERNS = exports.SUPPORTED_EXTENSIONS = exports.ISO639_1_REGEX = void 0;
+// ─────────────────────────────────────────────────────────────
+// Config
+// ─────────────────────────────────────────────────────────────
+exports.ISO639_1_REGEX = /^[a-z]{2}$/;
+// Re-export constants from runtime/types (single source of truth)
+var types_1 = require("./runtime/types");
+Object.defineProperty(exports, "SUPPORTED_EXTENSIONS", { enumerable: true, get: function () { return types_1.SUPPORTED_EXTENSIONS; } });
+Object.defineProperty(exports, "EXCLUDED_PATTERNS", { enumerable: true, get: function () { return types_1.EXCLUDED_PATTERNS; } });
+Object.defineProperty(exports, "JSX_TRANSLATABLE_ATTRS", { enumerable: true, get: function () { return types_1.JSX_TRANSLATABLE_ATTRS; } });

package/dist/utils/ast-helpers.d.ts

@@ -0,0 +1,57 @@
+import type { NodePath } from '@babel/traverse';
+import generate from '@babel/generator';
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+/**
+ * Engine v2 AST helpers.
+ *
+ * Copied from v1 to preserve parsing/transformation behavior while v2 is
+ * stabilized.
+ */
+export interface ParseOptions {
+    sourceType?: 'module' | 'script' | 'unambiguous';
+    isTypeScript?: boolean;
+    isJSX?: boolean;
+    filename?: string;
+}
+export declare function parseCode(code: string, options?: ParseOptions): t.File;
+export declare function generateCode(ast: t.File, originalCode?: string): string;
+/**
+ * With `retainLines`, statements the injector adds (which have no source
+ * location) are printed on the line of the preceding token, e.g.
+ * `function Page() {const t = useTranslations();`. Move each such statement
+ * that directly follows a `{` onto its own line, indented like the body.
+ */
+export declare function placeStatementsOnOwnLines(code: string, statements: string[]): string;
+export declare function isJSXText(node: t.Node): node is t.JSXText;
+export declare function isAlreadyTranslated(node: t.Node, path: NodePath): boolean;
+export declare function isNonTranslatableContext(path: NodePath): boolean;
+export declare function getComponentName(path: NodePath): string | null;
+export declare function isInsideComponent(path: NodePath): boolean;
+/**
+ * The block body of the component `path` is in — where the translation hook
+ * goes. Skips callbacks (a hook inside `.map(…)` breaks the rules of hooks);
+ * null when there's no component with a block body.
+ */
+export declare function findComponentBody(path: NodePath): NodePath | null;
+export declare function hasTranslationImport(ast: t.File): boolean;
+export declare function hasTranslationHook(functionPath: NodePath): boolean;
+export declare function createTranslationImport(): t.ImportDeclaration;
+export declare function createTranslationHook(): t.VariableDeclaration;
+export declare function createTCall(key: string): t.CallExpression;
+export declare function createJSXTCall(key: string): t.JSXExpressionContainer;
+export declare function extractJSXTextContent(node: t.JSXText): string;
+export declare function getParentContext(path: NodePath): {
+    parentContext: string;
+    siblingGroupId: string;
+} | null;
+export declare function extractExpressionContent(node: t.Node, variables?: string[]): string | null;
+export declare function extractConditionalContent(node: t.ConditionalExpression): {
+    consequent: string | null;
+    alternate: string | null;
+};
+/**
+ * Check if the file has a 'use client' directive
+ */
+export declare function hasUseClientDirective(ast: t.File): boolean;
+export { generate, t, traverse };