i18next-cli 0.9.0

package/src/extractor/parsers/comment-parser.ts

@@ -0,0 +1,125 @@
+import type { PluginContext, I18nextToolkitConfig } from '../../types'
+
+/**
+ * Extracts translation keys from comments in source code using regex patterns.
+ * Supports extraction from single-line (//) and multi-line comments.
+ *
+ * @param code - The source code to analyze
+ * @param functionNames - Array of function names to look for (e.g., ['t', 'i18n.t'])
+ * @param pluginContext - Context object with helper methods to add found keys
+ * @param config - Configuration object containing extraction settings
+ *
+ * @example
+ * ```typescript
+ * const code = `
+ *   // t('user.name', 'User Name')
+ *   /* t('app.title', { defaultValue: 'My App', ns: 'common' }) *\/
+ * `
+ *
+ * const context = createPluginContext(allKeys)
+ * extractKeysFromComments(code, ['t'], context, config)
+ * // Extracts: user.name and app.title with their respective settings
+ * ```
+ */
+export function extractKeysFromComments (
+  code: string,
+  functionNames: string[],
+  pluginContext: PluginContext,
+  config: I18nextToolkitConfig
+): void {
+  const functionPattern = functionNames
+    .map(n => n.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|')
+  const keyRegex = new RegExp(`(?:${functionPattern})\\s*\\(\\s*(['"])([^'"]+)\\1`, 'g')
+
+  const commentTexts = collectCommentTexts(code)
+
+  for (const text of commentTexts) {
+    let match: RegExpExecArray | null
+    while ((match = keyRegex.exec(text)) !== null) {
+      let key = match[2]
+      let ns: string | undefined
+      const remainder = text.slice(match.index + match[0].length)
+
+      const defaultValue = parseDefaultValueFromComment(remainder)
+      // 1. Check for namespace in options object first (e.g., { ns: 'common' })
+      ns = parseNsFromComment(remainder)
+
+      // 2. If not in options, check for separator in key (e.g., 'common:button.save')
+      const nsSeparator = config.extract.nsSeparator ?? ':'
+      if (!ns && nsSeparator && key.includes(nsSeparator)) {
+        const parts = key.split(nsSeparator)
+        ns = parts.shift()
+        key = parts.join(nsSeparator)
+      }
+      if (!ns) ns = config.extract.defaultNS
+
+      pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key })
+    }
+  }
+}
+
+/**
+ * Parses default value from the remainder of a comment after a translation function call.
+ * Supports both string literals and object syntax with defaultValue property.
+ *
+ * @param remainder - The remaining text after the translation key
+ * @returns The parsed default value or undefined if none found
+ *
+ * @internal
+ */
+function parseDefaultValueFromComment (remainder: string): string | undefined {
+  // Simple string default: , 'VALUE' or , "VALUE"
+  const dvString = /^\s*,\s*(['"])(.*?)\1/.exec(remainder)
+  if (dvString) return dvString[2]
+
+  // Object with defaultValue: , { defaultValue: 'VALUE', ... }
+  const dvObj = /^\s*,\s*\{[^}]*defaultValue\s*:\s*(['"])(.*?)\1/.exec(remainder)
+  if (dvObj) return dvObj[2]
+
+  return undefined
+}
+
+/**
+ * Parses namespace from the remainder of a comment after a translation function call.
+ * Looks for namespace specified in options object syntax.
+ *
+ * @param remainder - The remaining text after the translation key
+ * @returns The parsed namespace or undefined if none found
+ *
+ * @internal
+ */
+function parseNsFromComment (remainder: string): string | undefined {
+  // Look for ns in an options object, e.g., { ns: 'common' }
+  const nsObj = /^\s*,\s*\{[^}]*ns\s*:\s*(['"])(.*?)\1/.exec(remainder)
+  if (nsObj) return nsObj[2]
+
+  return undefined
+}
+
+/**
+ * Collects all comment texts from source code, both single-line and multi-line.
+ * Deduplicates comments to avoid processing the same text multiple times.
+ *
+ * @param src - The source code to extract comments from
+ * @returns Array of unique comment text content
+ *
+ * @internal
+ */
+function collectCommentTexts (src: string): string[] {
+  const texts: string[] = []
+  const seen = new Set<string>()
+
+  const commentRegex = /\/\/(.*)|\/\*([\s\S]*?)\*\//g
+  let cmatch: RegExpExecArray | null
+  while ((cmatch = commentRegex.exec(src)) !== null) {
+    const content = cmatch[1] ?? cmatch[2]
+    const s = content.trim()
+    if (s && !seen.has(s)) {
+      seen.add(s)
+      texts.push(s)
+    }
+  }
+
+  return texts
+}

package/src/extractor/parsers/jsx-parser.ts

@@ -0,0 +1,166 @@
+import type { JSXElement } from '@swc/core'
+import type { ExtractedKey, I18nextToolkitConfig } from '../../types'
+
+/**
+ * Extracts translation keys from JSX Trans components.
+ *
+ * This function handles various Trans component patterns:
+ * - Explicit i18nKey prop: `<Trans i18nKey="my.key">content</Trans>`
+ * - Implicit keys from children: `<Trans>Hello World</Trans>`
+ * - Namespace specification: `<Trans ns="common">content</Trans>`
+ * - Default values: `<Trans defaults="Default text">content</Trans>`
+ * - Pluralization: `<Trans count={count}>content</Trans>`
+ * - HTML preservation: `<Trans>Hello <strong>world</strong></Trans>`
+ *
+ * @param node - The JSX element node to process
+ * @param config - The toolkit configuration containing extraction settings
+ * @returns Extracted key information or null if no valid key found
+ *
+ * @example
+ * ```typescript
+ * // Input JSX:
+ * // <Trans i18nKey="welcome.title" ns="home" defaults="Welcome!">
+ * //   Welcome to our <strong>amazing</strong> app!
+ * // </Trans>
+ *
+ * const result = extractFromTransComponent(jsxNode, config)
+ * // Returns: {
+ * //   key: 'welcome.title',
+ * //   ns: 'home',
+ * //   defaultValue: 'Welcome!',
+ * //   hasCount: false
+ * // }
+ * ```
+ */
+export function extractFromTransComponent (node: JSXElement, config: I18nextToolkitConfig): ExtractedKey | null {
+  const i18nKeyAttr = node.opening.attributes?.find(
+    (attr) =>
+      attr.type === 'JSXAttribute' &&
+      attr.name.type === 'Identifier' &&
+      attr.name.value === 'i18nKey'
+  )
+
+  const defaultsAttr = node.opening.attributes?.find(
+    (attr) =>
+      attr.type === 'JSXAttribute' &&
+      attr.name.type === 'Identifier' &&
+      attr.name.value === 'defaults'
+  )
+
+  const countAttr = node.opening.attributes?.find(
+    (attr) =>
+      attr.type === 'JSXAttribute' &&
+      attr.name.type === 'Identifier' &&
+      attr.name.value === 'count'
+  )
+  const hasCount = !!countAttr
+
+  let key: string
+  if (i18nKeyAttr?.type === 'JSXAttribute' && i18nKeyAttr.value?.type === 'StringLiteral') {
+    key = i18nKeyAttr.value.value
+  } else {
+    key = serializeJSXChildren(node.children, config)
+  }
+
+  if (!key) {
+    return null
+  }
+
+  const nsAttr = node.opening.attributes?.find(
+    (attr) =>
+      attr.type === 'JSXAttribute' && attr.name.type === 'Identifier' && attr.name.value === 'ns'
+  )
+  const ns = nsAttr?.type === 'JSXAttribute' && nsAttr.value?.type === 'StringLiteral'
+    ? nsAttr.value.value
+    : undefined
+
+  let defaultValue = config.extract.defaultValue || ''
+  if (defaultsAttr?.type === 'JSXAttribute' && defaultsAttr.value?.type === 'StringLiteral') {
+    defaultValue = defaultsAttr.value.value
+  } else {
+    defaultValue = serializeJSXChildren(node.children, config)
+  }
+
+  return { key, ns, defaultValue: defaultValue || key, hasCount }
+}
+
+/**
+ * Serializes JSX children into a string representation suitable for i18next.
+ *
+ * This function converts JSX children into the format expected by i18next:
+ * - Text nodes are preserved as-is
+ * - HTML elements are converted to indexed placeholders or preserved if allowed
+ * - JSX expressions become interpolation placeholders: `{{variable}}`
+ * - Fragments are flattened
+ * - Whitespace is normalized
+ *
+ * The serialization respects the `transKeepBasicHtmlNodesFor` configuration
+ * to determine which HTML tags should be preserved vs. converted to indexed placeholders.
+ *
+ * @param children - Array of JSX child nodes to serialize
+ * @param config - Configuration containing HTML preservation settings
+ * @returns Serialized string representation
+ *
+ * @example
+ * ```typescript
+ * // JSX: Hello <strong>{{name}}</strong>, you have <Link to="/msgs">{{count}} messages</Link>.
+ * // With transKeepBasicHtmlNodesFor: ['strong']
+ * // Returns: "Hello <strong>{{name}}</strong>, you have <1>{{count}} messages</1>."
+ * //          (strong preserved, Link becomes indexed placeholder <1>)
+ *
+ * const serialized = serializeJSXChildren(children, config)
+ * ```
+ *
+ * @internal
+ */
+function serializeJSXChildren (children: any[], config: I18nextToolkitConfig): string {
+  const allowedTags = new Set(config.extract.transKeepBasicHtmlNodesFor ?? ['br', 'strong', 'i', 'p'])
+
+  /**
+   * Recursively processes JSX children and converts them to string format.
+   *
+   * @param children - Array of child nodes to process
+   * @returns Serialized string content
+   */
+  function serializeChildren (children: any[]): string {
+    let out = ''
+    // Use forEach to get the direct index of each child in the array
+    children.forEach((child, index) => {
+      if (child.type === 'JSXText') {
+        out += child.value
+      } else if (child.type === 'JSXExpressionContainer') {
+        const expr = child.expression
+        if (expr.type === 'StringLiteral') {
+          out += expr.value
+        } else if (expr.type === 'Identifier') {
+          out += `{{${expr.value}}}`
+        } else if (expr.type === 'ObjectExpression') {
+          const prop = expr.properties[0]
+          if (prop && prop.type === 'Identifier') {
+            out += `{{${prop.value}}}`
+          }
+        }
+      } else if (child.type === 'JSXElement') {
+        let tag
+        if (child.opening.name.type === 'Identifier') {
+          tag = child.opening.name.value
+        }
+
+        const innerContent = serializeChildren(child.children)
+
+        if (tag && allowedTags.has(tag)) {
+          // If the tag is in the allowed list, preserve it
+          out += `<${tag}>${innerContent}</${tag}>`
+        } else {
+          // Otherwise, replace it with ITS INDEX IN THE CHILDREN ARRAY
+          out += `<${index}>${innerContent}</${index}>`
+        }
+      } else if (child.type === 'JSXFragment') {
+        out += serializeChildren(child.children)
+      }
+    })
+    return out
+  }
+
+  return serializeChildren(children).trim().replace(/\s{2,}/g, ' ')
+}

package/src/extractor/plugin-manager.ts

@@ -0,0 +1,54 @@
+import type { ExtractedKey, PluginContext } from '../types'
+
+/**
+ * Initializes an array of plugins by calling their setup hooks.
+ * This function should be called before starting the extraction process.
+ *
+ * @param plugins - Array of plugin objects to initialize
+ *
+ * @example
+ * ```typescript
+ * const plugins = [customPlugin(), anotherPlugin()]
+ * await initializePlugins(plugins)
+ * // All plugin setup hooks have been called
+ * ```
+ */
+export async function initializePlugins (plugins: any[]): Promise<void> {
+  for (const plugin of plugins) {
+    await plugin.setup?.()
+  }
+}
+
+/**
+ * Creates a plugin context object that provides helper methods for plugins.
+ * The context allows plugins to add extracted keys to the main collection.
+ *
+ * @param allKeys - The main map where extracted keys are stored
+ * @returns A context object with helper methods for plugins
+ *
+ * @example
+ * ```typescript
+ * const allKeys = new Map()
+ * const context = createPluginContext(allKeys)
+ *
+ * // Plugin can now add keys
+ * context.addKey({
+ *   key: 'my.custom.key',
+ *   defaultValue: 'Default Value',
+ *   ns: 'common'
+ * })
+ * ```
+ */
+export function createPluginContext (allKeys: Map<string, ExtractedKey>): PluginContext {
+  return {
+    addKey: (keyInfo: ExtractedKey) => {
+      // Use namespace in the unique map key to avoid collisions across namespaces
+      const uniqueKey = `${keyInfo.ns ?? 'translation'}:${keyInfo.key}`
+
+      if (!allKeys.has(uniqueKey)) {
+        const defaultValue = keyInfo.defaultValue ?? keyInfo.key
+        allKeys.set(uniqueKey, { ...keyInfo, defaultValue })
+      }
+    },
+  }
+}

package/src/extractor.ts

@@ -0,0 +1,15 @@
+// src/index.ts
+import { runExtractor, extract } from './extractor/core/extractor'
+import { findKeys } from './extractor/core/key-finder'
+import { getTranslations } from './extractor/core/translation-manager'
+import { ASTVisitors } from './extractor/parsers/ast-visitors'
+import type { PluginContext } from './types'
+
+export {
+  runExtractor,
+  extract,
+  findKeys,
+  getTranslations,
+  ASTVisitors,
+  PluginContext,
+}

package/src/heuristic-config.ts

@@ -0,0 +1,64 @@
+import { glob } from 'glob'
+import { readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { I18nextToolkitConfig } from './types'
+
+// A list of common glob patterns for the primary language ('en') or ('dev') translation files.
+const HEURISTIC_PATTERNS = [
+  'public/locales/dev/*.json',
+  'locales/dev/*.json',
+  'src/locales/dev/*.json',
+  'src/assets/locales/dev/*.json',
+  'public/locales/en/*.json',
+  'locales/en/*.json',
+  'src/locales/en/*.json',
+  'src/assets/locales/en/*.json',
+]
+
+/**
+ * Attempts to automatically detect the project's i18n structure by searching for
+ * common translation file locations.
+ *
+ * @returns A promise that resolves to a partial I18nextToolkitConfig if detection
+ * is successful, otherwise null.
+ */
+export async function detectConfig (): Promise<Partial<I18nextToolkitConfig> | null> {
+  for (const pattern of HEURISTIC_PATTERNS) {
+    const files = await glob(pattern, { ignore: 'node_modules/**' })
+
+    if (files.length > 0) {
+      const firstFile = files[0]
+      const basePath = dirname(dirname(firstFile))
+
+      try {
+        const allDirs = await readdir(basePath)
+        // CORRECTED REGEX: Now accepts 'dev' in addition to standard locale codes.
+        let locales = allDirs.filter(dir => /^(dev|[a-z]{2}(-[A-Z]{2})?)$/.test(dir))
+
+        if (locales.length > 0) {
+          // Prioritization Logic
+          locales.sort()
+          if (locales.includes('dev')) {
+            locales = ['dev', ...locales.filter(l => l !== 'dev')]
+          }
+          if (locales.includes('en')) {
+            locales = ['en', ...locales.filter(l => l !== 'en')]
+          }
+
+          return {
+            locales,
+            extract: {
+              input: ['src/**/*.{js,jsx,ts,tsx}'],
+              output: join(basePath, '{{language}}', '{{namespace}}.json'),
+              primaryLanguage: locales.includes('en') ? 'en' : locales[0],
+            },
+          }
+        }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  return null
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export type {
+  I18nextToolkitConfig,
+  Plugin,
+  PluginContext,
+  ExtractedKey
+} from './types'
+export { defineConfig } from './config'
+export {
+  extract,
+  findKeys,
+  getTranslations
+} from './extractor'

package/src/init.ts

@@ -0,0 +1,156 @@
+import inquirer from 'inquirer'
+import { writeFile, readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/**
+ * Determines if the current project is configured as an ESM project.
+ * Checks the package.json file for `"type": "module"`.
+ *
+ * @returns Promise resolving to true if ESM, false if CommonJS
+ *
+ * @example
+ * ```typescript
+ * const isESM = await isEsmProject()
+ * if (isESM) {
+ *   // Generate ESM syntax
+ * } else {
+ *   // Generate CommonJS syntax
+ * }
+ * ```
+ */
+async function isEsmProject (): Promise<boolean> {
+  try {
+    const packageJsonPath = resolve(process.cwd(), 'package.json')
+    const content = await readFile(packageJsonPath, 'utf-8')
+    const packageJson = JSON.parse(content)
+    return packageJson.type === 'module'
+  } catch {
+    return true // Default to ESM if package.json is not found or readable
+  }
+}
+
+/**
+ * Interactive setup wizard for creating a new i18next-cli configuration file.
+ *
+ * This function provides a guided setup experience that:
+ * 1. Asks the user for their preferred configuration file type (TypeScript or JavaScript)
+ * 2. Collects basic project settings (locales, input patterns, output paths)
+ * 3. Detects the project module system (ESM vs CommonJS) for JavaScript files
+ * 4. Generates an appropriate configuration file with proper syntax
+ * 5. Provides helpful defaults for common use cases
+ *
+ * The generated configuration includes:
+ * - Locale specification
+ * - Input file patterns for source scanning
+ * - Output path templates with placeholders
+ * - Proper imports and exports for the detected module system
+ * - JSDoc type annotations for JavaScript files
+ *
+ * @example
+ * ```typescript
+ * // Run the interactive setup
+ * await runInit()
+ *
+ * // This will create either:
+ * // - i18next.config.ts (TypeScript)
+ * // - i18next.config.js (JavaScript ESM/CommonJS)
+ * ```
+ */
+export async function runInit () {
+  console.log('Welcome to the i18next-cli setup wizard!')
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'fileType',
+      message: 'What kind of configuration file do you want?',
+      choices: ['TypeScript (i18next.config.ts)', 'JavaScript (i18next.config.js)'],
+    },
+    {
+      type: 'input',
+      name: 'locales',
+      message: 'What locales does your project support? (comma-separated)',
+      default: 'en,de,fr',
+      filter: (input: string) => input.split(',').map(s => s.trim()),
+    },
+    {
+      type: 'input',
+      name: 'input',
+      message: 'What is the glob pattern for your source files?',
+      default: 'src/**/*.{js,jsx,ts,tsx}',
+    },
+    {
+      type: 'input',
+      name: 'output',
+      message: 'What is the path for your output resource files?',
+      default: 'public/locales/{{language}}/{{namespace}}.json',
+    },
+  ])
+
+  const isTypeScript = answers.fileType.includes('TypeScript')
+  const isEsm = await isEsmProject()
+  const fileName = isTypeScript ? 'i18next.config.ts' : 'i18next.config.js'
+
+  const configObject = {
+    locales: answers.locales,
+    extract: {
+      input: answers.input,
+      output: answers.output,
+    },
+  }
+
+  // Helper to serialize a JS value as a JS literal:
+  function toJs (value: any, indent = 2, level = 0): string {
+    const pad = (n: number) => ' '.repeat(n * indent)
+    const currentPad = pad(level)
+    const nextPad = pad(level + 1)
+
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+      return JSON.stringify(value)
+    }
+    if (typeof value === 'string') {
+      return JSON.stringify(value) // keeps double quotes and proper escaping
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return '[]'
+      const items = value.map(v => `${nextPad}${toJs(v, indent, level + 1)}`).join(',\n')
+      return `[\n${items}\n${currentPad}]`
+    }
+    if (typeof value === 'object') {
+      const keys = Object.keys(value)
+      if (keys.length === 0) return '{}'
+      const entries = keys.map(key => {
+        // Use unquoted key if it's a valid identifier otherwise JSON.stringify(key)
+        const validId = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        const printedKey = validId ? key : JSON.stringify(key)
+        return `${nextPad}${printedKey}: ${toJs(value[key], indent, level + 1)}`
+      }).join(',\n')
+      return `{\n${entries}\n${currentPad}}`
+    }
+
+    // Fallback
+    return JSON.stringify(value)
+  }
+
+  let fileContent = ''
+  if (isTypeScript) {
+    fileContent = `import { defineConfig } from 'i18next-cli';
+
+export default defineConfig(${toJs(configObject)});`
+  } else if (isEsm) {
+    fileContent = `import { defineConfig } from 'i18next-cli';
+
+/** @type {import('i18next-cli').I18nextToolkitConfig} */
+export default defineConfig(${toJs(configObject)});`
+  } else { // CJS
+    fileContent = `const { defineConfig } = require('i18next-cli');
+
+/** @type {import('i18next-cli').I18nextToolkitConfig} */
+module.exports = defineConfig(${toJs(configObject)});`
+  }
+
+  const outputPath = resolve(process.cwd(), fileName)
+  await writeFile(outputPath, fileContent.trim())
+
+  console.log(`✅ Configuration file created at: ${outputPath}`)
+}