i18next-cli 0.9.0

package/src/extractor/core/extractor.ts

@@ -0,0 +1,195 @@
+import ora from 'ora'
+import chalk from 'chalk'
+import { parse } from '@swc/core'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { Logger, ExtractedKey, PluginContext, I18nextToolkitConfig } from '../../types'
+import { findKeys } from './key-finder'
+import { getTranslations } from './translation-manager'
+import { validateExtractorConfig, ExtractorError } from '../../utils/validation'
+import { createPluginContext } from '../plugin-manager'
+import { extractKeysFromComments } from '../parsers/comment-parser'
+import { ASTVisitors } from '../parsers/ast-visitors'
+import { ConsoleLogger } from '../../utils/logger'
+
+/**
+ * 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,
+  logger: Logger = new ConsoleLogger()
+): Promise<boolean> {
+  if (!config.extract.primaryLanguage) config.extract.primaryLanguage = config.locales[0] || 'en'
+  if (!config.extract.secondaryLanguages) config.extract.secondaryLanguages = config.locales.filter((l: string) => l !== config?.extract?.primaryLanguage)
+
+  validateExtractorConfig(config)
+
+  const spinner = ora('Running i18next key extractor...\n').start()
+
+  try {
+    const allKeys = await findKeys(config, logger)
+    spinner.text = `Found ${allKeys.size} unique keys. Updating translation files...`
+
+    const results = await getTranslations(allKeys, config)
+
+    let anyFileUpdated = false
+    for (const result of results) {
+      if (result.updated) {
+        anyFileUpdated = true
+        await mkdir(dirname(result.path), { recursive: true })
+        await writeFile(result.path, JSON.stringify(result.newTranslations, null, 2))
+        logger.info(chalk.green(`Updated: ${result.path}`))
+      }
+    }
+
+    spinner.succeed(chalk.bold('Extraction complete!'))
+    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,
+  config: I18nextToolkitConfig,
+  logger: Logger,
+  allKeys: Map<string, ExtractedKey>
+): Promise<void> {
+  try {
+    let code = await readFile(file, 'utf-8')
+
+    // Run onLoad hooks from plugins
+    for (const plugin of (config.plugins || [])) {
+      code = (await plugin.onLoad?.(code, file)) ?? code
+    }
+
+    const ast = await parse(code, {
+      syntax: 'typescript',
+      tsx: true,
+      comments: true
+    })
+
+    const pluginContext = createPluginContext(allKeys)
+
+    // Extract keys from comments
+    extractKeysFromComments(code, config.extract.functions || ['t'], pluginContext, config)
+
+    // Extract keys from AST using visitors
+    const astVisitors = new ASTVisitors(
+      config,
+      pluginContext,
+      logger
+    )
+
+    astVisitors.visit(ast)
+
+    // Run plugin visitors
+    if ((config.plugins || []).length > 0) {
+      traverseEveryNode(ast, (config.plugins || []), pluginContext)
+    }
+  } catch (error) {
+    throw new ExtractorError('Failed to process file', file, error as Error)
+  }
+}
+
+/**
+ * Recursively traverses AST nodes and calls plugin onVisitNode hooks.
+ *
+ * @param node - The AST node to traverse
+ * @param plugins - Array of plugins to run hooks for
+ * @param pluginContext - Context object with helper methods for plugins
+ *
+ * @internal
+ */
+function traverseEveryNode (node: any, plugins: any[], pluginContext: PluginContext): void {
+  if (!node || typeof node !== 'object') return
+
+  // Call plugins for this node
+  for (const plugin of plugins) {
+    try {
+      plugin.onVisitNode?.(node, pluginContext)
+    } catch (err) {
+      console.warn(`Plugin ${plugin.name} onVisitNode failed:`, err)
+    }
+  }
+
+  for (const key of Object.keys(node)) {
+    const child = node[key]
+    if (Array.isArray(child)) {
+      for (const c of child) {
+        if (c && typeof c === 'object') traverseEveryNode(c, plugins, pluginContext)
+      }
+    } else if (child && typeof child === 'object') {
+      traverseEveryNode(child, plugins, pluginContext)
+    }
+  }
+}
+
+/**
+ * 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) {
+  if (!config.extract.primaryLanguage) config.extract.primaryLanguage = config.locales[0]
+  if (!config.extract.secondaryLanguages) config.extract.secondaryLanguages = config.locales.filter((l: string) => l !== config?.extract?.primaryLanguage)
+  if (!config.extract.functions) config.extract.functions = ['t']
+  if (!config.extract.transComponents) config.extract.transComponents = ['Trans']
+  const allKeys = await findKeys(config)
+  return getTranslations(allKeys, config)
+}

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

@@ -0,0 +1,70 @@
+import { glob } from 'glob'
+import type { ExtractedKey, Logger, I18nextToolkitConfig } from '../../types'
+import { processFile } from './extractor'
+import { ConsoleLogger } from '../../utils/logger'
+import { initializePlugins } from '../plugin-manager'
+
+/**
+ * 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'],
+ *     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<Map<string, ExtractedKey>> {
+  const sourceFiles = await processSourceFiles(config)
+  const allKeys = new Map<string, ExtractedKey>()
+
+  await initializePlugins(config.plugins || [])
+
+  for (const file of sourceFiles) {
+    await processFile(file, config, logger, allKeys)
+  }
+
+  // Run onEnd hooks
+  for (const plugin of (config.plugins || [])) {
+    await plugin.onEnd?.(allKeys)
+  }
+
+  return allKeys
+}
+
+/**
+ * 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[]> {
+  return await glob(config.extract.input, {
+    ignore: 'node_modules/**',
+    cwd: process.cwd(),
+  })
+}

package/src/extractor/core/translation-manager.ts

@@ -0,0 +1,115 @@
+import { TranslationResult, ExtractedKey, I18nextToolkitConfig } from '../../types'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { getNestedValue, setNestedValue, getNestedKeys } from '../../utils/nested-object'
+import { getOutputPath } from '../../utils/file-utils'
+
+/**
+ * Converts a glob pattern to a regular expression for matching keys
+ * @param glob - The glob pattern to convert
+ * @returns A RegExp object that matches the glob pattern
+ */
+function globToRegex (glob: string): RegExp {
+  const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+  const regexString = `^${escaped.replace(/\*/g, '.*')}$`
+  return new RegExp(regexString)
+}
+
+/**
+ * Processes extracted translation keys and generates translation files for all configured locales.
+ *
+ * This function:
+ * 1. Groups keys by namespace
+ * 2. For each locale and namespace combination:
+ *    - Reads existing translation files
+ *    - Preserves keys matching `preservePatterns`
+ *    - Merges in newly extracted keys
+ *    - Uses primary language defaults or empty strings for secondary languages
+ *    - Maintains key sorting based on configuration
+ * 3. Determines if files need updating by comparing content
+ *
+ * @param keys - Map of extracted translation keys with metadata
+ * @param config - The i18next toolkit configuration object
+ * @returns Promise resolving to array of translation results with update status
+ *
+ * @example
+ * ```typescript
+ * const keys = new Map([
+ *   ['translation:welcome', { key: 'welcome', defaultValue: 'Welcome!', ns: 'translation' }],
+ *   ['common:button.save', { key: 'button.save', defaultValue: 'Save', ns: 'common' }]
+ * ])
+ *
+ * const results = await getTranslations(keys, config)
+ * // Results contain update status and new/existing translations for each locale
+ * ```
+ */
+export async function getTranslations (
+  keys: Map<string, ExtractedKey>,
+  config: I18nextToolkitConfig
+): Promise<TranslationResult[]> {
+  const defaultNS = config.extract.defaultNS ?? 'translation'
+  const keySeparator = config.extract.keySeparator ?? '.'
+  const preservePatterns = (config.extract.preservePatterns ?? []).map(globToRegex)
+  if (!config.extract.primaryLanguage) config.extract.primaryLanguage = config.locales[0] || 'en'
+  if (!config.extract.secondaryLanguages) config.extract.secondaryLanguages = config.locales.filter((l: string) => l !== config.extract.primaryLanguage)
+
+  // Group keys by namespace
+  const keysByNS = new Map<string, ExtractedKey[]>()
+  for (const key of keys.values()) {
+    const ns = key.ns || defaultNS
+    if (!keysByNS.has(ns)) {
+      keysByNS.set(ns, [])
+    }
+    keysByNS.get(ns)!.push(key)
+  }
+
+  const results: TranslationResult[] = []
+
+  for (const locale of config.locales) {
+    for (const [ns, nsKeys] of keysByNS.entries()) {
+      const outputPath = getOutputPath(config.extract.output, locale, ns)
+
+      const fullPath = resolve(process.cwd(), outputPath)
+
+      let oldContent = ''
+      let existingTranslations: Record<string, any> = {}
+      try {
+        oldContent = await readFile(fullPath, 'utf-8')
+        existingTranslations = JSON.parse(oldContent)
+      } catch (e) { /* File doesn't exist, which is fine */ }
+
+      const newTranslations: Record<string, any> = {}
+
+      // 1. Preserve keys from existing translations that match patterns
+      const existingKeys = getNestedKeys(existingTranslations, keySeparator)
+      for (const existingKey of existingKeys) {
+        if (preservePatterns.some(re => re.test(existingKey))) {
+          const value = getNestedValue(existingTranslations, existingKey, keySeparator)
+          setNestedValue(newTranslations, existingKey, value, keySeparator)
+        }
+      }
+
+      // 2. Merge in newly found keys for this namespace
+      const sortedKeys = (config.extract.sort === false)
+        ? nsKeys
+        : nsKeys.sort((a, b) => a.key.localeCompare(b.key))
+      for (const { key, defaultValue } of sortedKeys) {
+        const existingValue = getNestedValue(existingTranslations, key, keySeparator)
+        const valueToSet = existingValue ?? (locale === config.extract?.primaryLanguage ? defaultValue : '')
+        setNestedValue(newTranslations, key, valueToSet, keySeparator)
+      }
+
+      const indentation = config.extract.indentation ?? 2
+      const newContent = JSON.stringify(newTranslations, null, indentation)
+
+      results.push({
+        path: fullPath,
+        updated: newContent !== oldContent,
+        newTranslations,
+        existingTranslations,
+      })
+    }
+  }
+
+  return results
+}

package/src/extractor/index.ts

@@ -0,0 +1,7 @@
+export * from './core/extractor'
+export * from './core/key-finder'
+export * from './core/translation-manager'
+export * from './parsers/ast-visitors'
+export * from './parsers/comment-parser'
+export * from './parsers/jsx-parser'
+export * from './plugin-manager'