i18next-cli 1.24.13 → 1.24.14

package/src/extractor/core/ast-visitors.ts

@@ -1,259 +0,0 @@
-import type { Module, Node } from '@swc/core'
-import type { PluginContext, I18nextToolkitConfig, Logger, ASTVisitorHooks, ScopeInfo } from '../../types'
-import { ScopeManager } from '../parsers/scope-manager'
-import { ExpressionResolver } from '../parsers/expression-resolver'
-import { CallExpressionHandler } from '../parsers/call-expression-handler'
-import { JSXHandler } from '../parsers/jsx-handler'
-
-/**
- * AST visitor class that traverses JavaScript/TypeScript syntax trees to extract translation keys.
- *
- * This class implements a manual recursive walker that:
- * - Maintains scope information for tracking useTranslation and getFixedT calls
- * - Extracts keys from t() function calls with various argument patterns
- * - Handles JSX Trans components with complex children serialization
- * - Supports both string literals and selector API for type-safe keys
- * - Processes pluralization and context variants
- * - Manages namespace resolution from multiple sources
- *
- * The visitor respects configuration options for separators, function names,
- * component names, and other extraction settings.
- *
- * @example
- * ```typescript
- * const visitors = new ASTVisitors(config, pluginContext, logger)
- * visitors.visit(parsedAST)
- *
- * // The pluginContext will now contain all extracted keys
- * ```
- */
-export class ASTVisitors {
-  private readonly pluginContext: PluginContext
-  private readonly config: Omit<I18nextToolkitConfig, 'plugins'>
-  private readonly logger: Logger
-  private hooks: ASTVisitorHooks
-
-  public get objectKeys () {
-    return this.callExpressionHandler.objectKeys
-  }
-
-  private readonly scopeManager: ScopeManager
-  private readonly expressionResolver: ExpressionResolver
-  private readonly callExpressionHandler: CallExpressionHandler
-  private readonly jsxHandler: JSXHandler
-  private currentFile: string = ''
-  private currentCode: string = ''
-
-  /**
-   * Creates a new AST visitor instance.
-   *
-   * @param config - Toolkit configuration with extraction settings
-   * @param pluginContext - Context for adding discovered translation keys
-   * @param logger - Logger for warnings and debug information
-   */
-  constructor (
-    config: Omit<I18nextToolkitConfig, 'plugins'>,
-    pluginContext: PluginContext,
-    logger: Logger,
-    hooks?: ASTVisitorHooks,
-    expressionResolver?: ExpressionResolver
-  ) {
-    this.pluginContext = pluginContext
-    this.config = config
-    this.logger = logger
-    this.hooks = {
-      onBeforeVisitNode: hooks?.onBeforeVisitNode,
-      onAfterVisitNode: hooks?.onAfterVisitNode,
-      resolvePossibleKeyStringValues: hooks?.resolvePossibleKeyStringValues,
-      resolvePossibleContextStringValues: hooks?.resolvePossibleContextStringValues
-    }
-
-    this.scopeManager = new ScopeManager(config)
-    // use shared resolver when provided so captured enums/objects are visible across files
-    this.expressionResolver = expressionResolver ?? new ExpressionResolver(this.hooks)
-    this.callExpressionHandler = new CallExpressionHandler(
-      config,
-      pluginContext,
-      logger,
-      this.expressionResolver,
-      () => this.getCurrentFile(),
-      () => this.getCurrentCode()
-    )
-    this.jsxHandler = new JSXHandler(
-      config,
-      pluginContext,
-      this.expressionResolver,
-      () => this.getCurrentFile(),
-      () => this.getCurrentCode()
-    )
-  }
-
-  /**
-   * Main entry point for AST traversal.
-   * Creates a root scope and begins the recursive walk through the syntax tree.
-   *
-   * @param node - The root module node to traverse
-   */
-  public visit (node: Module): void {
-    // Reset any per-file scope state to avoid leaking scopes between files.
-    this.scopeManager.reset()
-    // Reset per-file captured variables in the expression resolver so variables from other files don't leak.
-    this.expressionResolver.resetFileSymbols()
-    this.scopeManager.enterScope() // Create the root scope for the file
-    this.walk(node)
-    this.scopeManager.exitScope()  // Clean up the root scope
-  }
-
-  /**
-   * Recursively walks through AST nodes, handling scoping and visiting logic.
-   *
-   * This is the core traversal method that:
-   * 1. Manages function scopes (enter/exit)
-   * 2. Dispatches to specific handlers based on node type
-   * 3. Recursively processes child nodes
-   * 4. Maintains proper scope cleanup
-   *
-   * @param node - The current AST node to process
-   *
-   * @private
-   */
-  private walk (node: Node | any): void {
-    if (!node) return
-
-    let isNewScope = false
-    // ENTER SCOPE for functions
-    if (node.type === 'Function' || node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression') {
-      this.scopeManager.enterScope()
-      isNewScope = true
-    }
-
-    this.hooks.onBeforeVisitNode?.(node)
-
-    // --- VISIT LOGIC ---
-    // Handle specific node types
-    switch (node.type) {
-      case 'VariableDeclarator':
-        this.scopeManager.handleVariableDeclarator(node)
-        // Capture simple variable initializers so the expressionResolver can
-        // resolve identifiers / member expressions that reference them.
-        this.expressionResolver.captureVariableDeclarator(node)
-        break
-      case 'TSEnumDeclaration':
-      case 'TsEnumDeclaration':
-      case 'TsEnumDecl':
-        // capture enums into resolver symbol table
-        this.expressionResolver.captureEnumDeclaration(node)
-        break
-      case 'CallExpression':
-        this.callExpressionHandler.handleCallExpression(node, this.scopeManager.getVarFromScope.bind(this.scopeManager))
-        break
-      case 'JSXElement':
-        this.jsxHandler.handleJSXElement(node, this.scopeManager.getVarFromScope.bind(this.scopeManager))
-        break
-    }
-
-    this.hooks.onAfterVisitNode?.(node)
-
-    // --- END VISIT LOGIC ---
-
-    // --- RECURSION ---
-    // Recurse into the children of the current node
-    for (const key in node) {
-      if (key === 'span') continue
-
-      const child = node[key]
-      if (Array.isArray(child)) {
-        // Pre-scan array children to register VariableDeclarator-based scopes
-        // (e.g., `const { t } = useTranslation(...)`) before walking the rest
-        // of the items. This ensures that functions/arrow-functions defined
-        // earlier in the same block that reference t will resolve to the
-        // correct scope even if the `useTranslation` declarator appears later.
-        for (const item of child) {
-          if (!item || typeof item !== 'object') continue
-
-          // Direct declarator present in arrays (rare)
-          if (item.type === 'VariableDeclarator') {
-            this.scopeManager.handleVariableDeclarator(item)
-            this.expressionResolver.captureVariableDeclarator(item)
-            continue
-          }
-          // enum declarations can appear as ExportDeclaration.declaration earlier; be permissive
-          if (item && item.id && Array.isArray(item.members)) {
-            this.expressionResolver.captureEnumDeclaration(item)
-            // continue to allow further traversal
-          }
-          // Common case: VariableDeclaration which contains .declarations (VariableDeclarator[])
-          if (item.type === 'VariableDeclaration' && Array.isArray(item.declarations)) {
-            for (const decl of item.declarations) {
-              if (decl && typeof decl === 'object' && decl.type === 'VariableDeclarator') {
-                this.scopeManager.handleVariableDeclarator(decl)
-                this.expressionResolver.captureVariableDeclarator(decl)
-              }
-            }
-          }
-        }
-        for (const item of child) {
-          // Be less strict: if it's a non-null object, walk it.
-          // This allows traversal into nodes that might not have a `.type` property
-          // but still contain other valid AST nodes.
-          if (item && typeof item === 'object') {
-            this.walk(item)
-          }
-        }
-      } else if (child && typeof child === 'object') {
-        // The condition for single objects should be the same as for array items.
-        // Do not require `child.type`. This allows traversal into class method bodies.
-        this.walk(child)
-      }
-    }
-    // --- END RECURSION ---
-
-    // LEAVE SCOPE for functions
-    if (isNewScope) {
-      this.scopeManager.exitScope()
-    }
-  }
-
-  /**
-   * Retrieves variable information from the scope chain.
-   * Searches from innermost to outermost scope.
-   *
-   * @param name - Variable name to look up
-   * @returns Scope information if found, undefined otherwise
-   *
-   * @private
-   */
-  public getVarFromScope (name: string): ScopeInfo | undefined {
-    return this.scopeManager.getVarFromScope(name)
-  }
-
-  /**
-   * Sets the current file path and code used by the extractor.
-   * Also resets the search index for location tracking.
-   */
-  public setCurrentFile (file: string, code: string): void {
-    this.currentFile = file
-    this.currentCode = code
-    // Reset search indexes when processing a new file
-    this.callExpressionHandler.resetSearchIndex()
-    this.jsxHandler.resetSearchIndex()
-  }
-
-  /**
-   * Returns the currently set file path.
-   *
-   * @returns The current file path as a string, or `undefined` if no file has been set.
-   * @remarks
-   * Use this to retrieve the file context that was previously set via `setCurrentFile`.
-   */
-  public getCurrentFile (): string {
-    return this.currentFile
-  }
-
-  /**
-   * @returns The full source code string for the file currently under processing.
-   */
-  public getCurrentCode (): string {
-    return this.currentCode
-  }
-}

package/src/extractor/core/extractor.ts

@@ -1,250 +0,0 @@
-import ora from 'ora'
-import chalk from 'chalk'
-import { parse } from '@swc/core'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, extname } from 'node:path'
-import type { Logger, I18nextToolkitConfig, Plugin, PluginContext } from '../../types'
-import { findKeys } from './key-finder'
-import { getTranslations } from './translation-manager'
-import { validateExtractorConfig, ExtractorError } from '../../utils/validation'
-import { extractKeysFromComments } from '../parsers/comment-parser'
-import { ASTVisitors } from './ast-visitors'
-import { ConsoleLogger } from '../../utils/logger'
-import { serializeTranslationFile } from '../../utils/file-utils'
-import { shouldShowFunnel, recordFunnelShown } from '../../utils/funnel-msg-tracker'
-
-/**
- * Main extractor function that runs the complete key extraction and file generation process.
- *
- * This is the primary entry point that:
- * 1. Validates configuration
- * 2. Sets up default sync options
- * 3. Finds all translation keys across source files
- * 4. Generates/updates translation files for all locales
- * 5. Provides progress feedback via spinner
- * 6. Returns whether any files were updated
- *
- * @param config - The i18next toolkit configuration object
- * @param logger - Logger instance for output (defaults to ConsoleLogger)
- * @returns Promise resolving to boolean indicating if any files were updated
- *
- * @throws {ExtractorError} When configuration validation fails or extraction process encounters errors
- *
- * @example
- * ```typescript
- * const config = await loadConfig()
- * const updated = await runExtractor(config)
- * if (updated) {
- *   console.log('Translation files were updated')
- * }
- * ```
- */
-export async function runExtractor (
-  config: I18nextToolkitConfig,
-  {
-    isWatchMode = false,
-    isDryRun = false,
-    syncPrimaryWithDefaults = false
-  }: {
-    isWatchMode?: boolean,
-    isDryRun?: boolean,
-    syncPrimaryWithDefaults?: boolean,
-  } = {},
-  logger: Logger = new ConsoleLogger()
-): Promise<boolean> {
-  config.extract.primaryLanguage ||= config.locales[0] || 'en'
-  config.extract.secondaryLanguages ||= config.locales.filter((l: string) => l !== config?.extract?.primaryLanguage)
-
-  // Ensure default function and component names are set if not provided.
-  config.extract.functions ||= ['t', '*.t']
-  config.extract.transComponents ||= ['Trans']
-
-  validateExtractorConfig(config)
-
-  const plugins = config.plugins || []
-
-  const spinner = ora('Running i18next key extractor...\n').start()
-
-  try {
-    const { allKeys, objectKeys } = await findKeys(config, logger)
-    spinner.text = `Found ${allKeys.size} unique keys. Updating translation files...`
-
-    const results = await getTranslations(allKeys, objectKeys, config, { syncPrimaryWithDefaults })
-
-    let anyFileUpdated = false
-    for (const result of results) {
-      if (result.updated) {
-        anyFileUpdated = true
-        // Only write files if it's not a dry run.
-        if (!isDryRun) {
-          const fileContent = serializeTranslationFile(
-            result.newTranslations,
-            config.extract.outputFormat,
-            config.extract.indentation
-          )
-          await mkdir(dirname(result.path), { recursive: true })
-          await writeFile(result.path, fileContent)
-          logger.info(chalk.green(`Updated: ${result.path}`))
-        }
-      }
-    }
-
-    // Run afterSync hooks from plugins
-    if (plugins.length > 0) {
-      spinner.text = 'Running post-extraction plugins...'
-      for (const plugin of plugins) {
-        await plugin.afterSync?.(results, config)
-      }
-    }
-
-    spinner.succeed(chalk.bold('Extraction complete!'))
-
-    // Show the funnel message only if files were actually changed.
-    if (anyFileUpdated) await printLocizeFunnel()
-
-    return anyFileUpdated
-  } catch (error) {
-    spinner.fail(chalk.red('Extraction failed.'))
-    // Re-throw or handle error
-    throw error
-  }
-}
-
-/**
- * Processes an individual source file for translation key extraction.
- *
- * This function:
- * 1. Reads the source file
- * 2. Runs plugin onLoad hooks for code transformation
- * 3. Parses the code into an Abstract Syntax Tree (AST) using SWC
- * 4. Extracts keys from comments using regex patterns
- * 5. Traverses the AST using visitors to find translation calls
- * 6. Runs plugin onVisitNode hooks for custom extraction logic
- *
- * @param file - Path to the source file to process
- * @param config - The i18next toolkit configuration object
- * @param logger - Logger instance for output
- * @param allKeys - Map to accumulate found translation keys
- *
- * @throws {ExtractorError} When file processing fails
- *
- * @internal
- */
-export async function processFile (
-  file: string,
-  plugins: Plugin[],
-  astVisitors: ASTVisitors,
-  pluginContext: PluginContext,
-  config: Omit<I18nextToolkitConfig, 'plugins'>,
-  logger: Logger = new ConsoleLogger()
-): Promise<void> {
-  try {
-    let code = await readFile(file, 'utf-8')
-
-    // Run onLoad hooks from plugins with error handling
-    for (const plugin of plugins) {
-      try {
-        const result = await plugin.onLoad?.(code, file)
-        if (result !== undefined) {
-          code = result
-        }
-      } catch (err) {
-        logger.warn(`Plugin ${plugin.name} onLoad failed:`, err)
-        // Continue with the original code if the plugin fails
-      }
-    }
-
-    // Determine parser options from file extension so .ts is not parsed as TSX
-    const fileExt = extname(file).toLowerCase()
-    const isTypeScriptFile = fileExt === '.ts' || fileExt === '.tsx' || fileExt === '.mts' || fileExt === '.cts'
-    const isTSX = fileExt === '.tsx'
-    const isJSX = fileExt === '.jsx'
-
-    let ast: any
-    try {
-      ast = await parse(code, {
-        syntax: isTypeScriptFile ? 'typescript' : 'ecmascript',
-        tsx: isTSX,
-        jsx: isJSX,
-        decorators: true,
-        dynamicImport: true,
-        comments: true,
-      })
-    } catch (err) {
-      // Some projects embed JSX/TSX inside .ts files. Try a one-time fallback parse
-      // enabling TSX when the file extension is `.ts`. If fallback fails, surface
-      // the original error as an ExtractorError.
-      if (fileExt === '.ts' && !isTSX) {
-        try {
-          ast = await parse(code, {
-            syntax: 'typescript',
-            tsx: true,
-            decorators: true,
-            dynamicImport: true,
-            comments: true,
-          })
-          logger.info?.(`Parsed ${file} using TSX fallback`)
-        } catch (err2) {
-          throw new ExtractorError('Failed to process file', file, err2 as Error)
-        }
-      } else {
-        throw new ExtractorError('Failed to process file', file, err as Error)
-      }
-    }
-
-    // "Wire up" the visitor's scope method to the context.
-    // This avoids a circular dependency while giving plugins access to the scope.
-    pluginContext.getVarFromScope = astVisitors.getVarFromScope.bind(astVisitors)
-
-    // Pass BOTH file and code
-    astVisitors.setCurrentFile(file, code)
-
-    // 3. FIRST: Visit the AST to build scope information
-    astVisitors.visit(ast)
-
-    // 4. THEN: Extract keys from comments with scope resolution (now scope info is available)
-    extractKeysFromComments(code, pluginContext, config, astVisitors.getVarFromScope.bind(astVisitors))
-  } catch (error) {
-    throw new ExtractorError('Failed to process file', file, error as Error)
-  }
-}
-
-/**
- * Simplified extraction function that returns translation results without file writing.
- * Used primarily for testing and programmatic access.
- *
- * @param config - The i18next toolkit configuration object
- * @returns Promise resolving to array of translation results
- *
- * @example
- * ```typescript
- * const results = await extract(config)
- * for (const result of results) {
- *   console.log(`${result.path}: ${result.updated ? 'Updated' : 'No changes'}`)
- * }
- * ```
- */
-export async function extract (config: I18nextToolkitConfig, { syncPrimaryWithDefaults = false }: { syncPrimaryWithDefaults?: boolean } = {}) {
-  config.extract.primaryLanguage ||= config.locales[0] || 'en'
-  config.extract.secondaryLanguages ||= config.locales.filter((l: string) => l !== config?.extract?.primaryLanguage)
-  config.extract.functions ||= ['t', '*.t']
-  config.extract.transComponents ||= ['Trans']
-  const { allKeys, objectKeys } = await findKeys(config)
-  return getTranslations(allKeys, objectKeys, config, { syncPrimaryWithDefaults })
-}
-
-/**
- * Prints a promotional message for the locize saveMissing workflow.
- * This message is shown after a successful extraction that resulted in changes.
- */
-async function printLocizeFunnel () {
-  if (!(await shouldShowFunnel('extract'))) return
-
-  console.log(chalk.yellow.bold('\n💡 Tip: Tired of running the extractor manually?'))
-  console.log('   Discover a real-time "push" workflow with `saveMissing` and Locize AI,')
-  console.log('   where keys are created and translated automatically as you code.')
-  console.log(`   Learn more: ${chalk.cyan('https://www.locize.com/blog/i18next-savemissing-ai-automation')}`)
-  console.log(`   Watch the video: ${chalk.cyan('https://youtu.be/joPsZghT3wM')}`)
-
-  return recordFunnelShown('extract')
-}

package/src/extractor/core/key-finder.ts

@@ -1,142 +0,0 @@
-import { glob } from 'glob'
-import type { Expression } from '@swc/core'
-import type { ExtractedKey, Logger, I18nextToolkitConfig, ASTVisitorHooks } from '../../types'
-import { processFile } from './extractor'
-import { ConsoleLogger } from '../../utils/logger'
-import { initializePlugins, createPluginContext } from '../plugin-manager'
-import { ASTVisitors } from './ast-visitors'
-import { ExpressionResolver } from '../parsers/expression-resolver'
-
-/**
- * Main function for finding translation keys across all source files in a project.
- *
- * This function orchestrates the key extraction process:
- * 1. Processes source files based on input patterns
- * 2. Initializes and manages plugins
- * 3. Processes each file through AST parsing and key extraction
- * 4. Runs plugin lifecycle hooks
- * 5. Returns a deduplicated map of all found keys
- *
- * @param config - The i18next toolkit configuration object
- * @param logger - Logger instance for output (defaults to ConsoleLogger)
- * @returns Promise resolving to a Map of unique translation keys with metadata
- *
- * @example
- * ```typescript
- * const config = {
- *   extract: {
- *     input: ['src/**\/*.{ts,tsx}'],
- *     functions: ['t', '*.t'],
- *     transComponents: ['Trans']
- *   }
- * }
- *
- * const keys = await findKeys(config)
- * console.log(`Found ${keys.size} unique translation keys`)
- * ```
- */
-export async function findKeys (
-  config: I18nextToolkitConfig,
-  logger: Logger = new ConsoleLogger()
-): Promise<{ allKeys: Map<string, ExtractedKey>, objectKeys: Set<string> }> {
-  const { plugins: pluginsOrUndefined, ...otherConfig } = config
-  const plugins = pluginsOrUndefined || []
-
-  const sourceFiles = await processSourceFiles(config)
-  const allKeys = new Map<string, ExtractedKey>()
-
-  // 1. Create the base context with config and logger.
-  const pluginContext = createPluginContext(allKeys, plugins, otherConfig, logger)
-
-  // 2. Create hooks for plugins to hook into AST
-  const hooks = {
-    onBeforeVisitNode: (node) => {
-      for (const plugin of plugins) {
-        try {
-          plugin.onVisitNode?.(node, pluginContext)
-        } catch (err) {
-          logger.warn(`Plugin ${plugin.name} onVisitNode failed:`, err)
-        }
-      }
-    },
-    resolvePossibleKeyStringValues: (expression: Expression) => {
-      return plugins.flatMap(plugin => {
-        try {
-          return plugin.extractKeysFromExpression?.(expression, config, logger) ?? []
-        } catch (err) {
-          logger.warn(`Plugin ${plugin.name} extractKeysFromExpression failed:`, err)
-          return []
-        }
-      })
-    },
-    resolvePossibleContextStringValues: (expression: Expression) => {
-      return plugins.flatMap(plugin => {
-        try {
-          return plugin.extractContextFromExpression?.(expression, config, logger) ?? []
-        } catch (err) {
-          logger.warn(`Plugin ${plugin.name} extractContextFromExpression failed:`, err)
-          return []
-        }
-      })
-    },
-  } satisfies ASTVisitorHooks
-
-  // 3. Create the visitor instance, passing it the context.
-  // Use a shared ExpressionResolver so captured enums/objects in one file are available when resolving MemberExpressions
-  const sharedExpressionResolver = new ExpressionResolver(hooks)
-  const astVisitors = new ASTVisitors(otherConfig, pluginContext, logger, hooks, sharedExpressionResolver)
-
-  // 4. "Wire up" the visitor's scope method to the context.
-  // This avoids a circular dependency while giving plugins access to the scope.
-  pluginContext.getVarFromScope = astVisitors.getVarFromScope.bind(astVisitors)
-
-  // 5. Initialize plugins
-  await initializePlugins(plugins)
-
-  // 6. Process each file
-  for (const file of sourceFiles) {
-    await processFile(file, plugins, astVisitors, pluginContext, otherConfig, logger)
-  }
-
-  // 7. Run onEnd hooks
-  for (const plugin of plugins) {
-    await plugin.onEnd?.(allKeys)
-  }
-
-  // Normalization: mark already-expanded plural keys
-  const pluralSeparator = otherConfig.extract?.pluralSeparator ?? '_'
-  const categories = ['zero', 'one', 'two', 'few', 'many', 'other']
-  for (const ek of allKeys.values()) {
-    const parts = String(ek.key).split(pluralSeparator)
-    const last = parts[parts.length - 1]
-    const isOrdinal = parts.length >= 3 && parts[parts.length - 2] === 'ordinal'
-    if (categories.includes(last) || (isOrdinal && categories.includes(last))) {
-      ;(ek as any).isExpandedPlural = true
-    }
-  }
-  return { allKeys, objectKeys: astVisitors.objectKeys }
-}
-
-/**
- * Processes source files using glob patterns from configuration.
- * Excludes node_modules by default and resolves relative to current working directory.
- *
- * @param config - The i18next toolkit configuration object
- * @returns Promise resolving to array of file paths to process
- *
- * @internal
- */
-async function processSourceFiles (config: I18nextToolkitConfig): Promise<string[]> {
-  const defaultIgnore = ['node_modules/**']
-
-  // Normalize the user's ignore option into an array
-  const userIgnore = Array.isArray(config.extract.ignore)
-    ? config.extract.ignore
-    : config.extract.ignore ? [config.extract.ignore] : []
-
-  return await glob(config.extract.input, {
-    // Combine default ignore patterns with user-configured ones
-    ignore: [...defaultIgnore, ...userIgnore],
-    cwd: process.cwd(),
-  })
-}