i18next-cli 0.9.0

package/src/linter.ts

@@ -0,0 +1,191 @@
+import { glob } from 'glob'
+import { readFile } from 'node:fs/promises'
+import { parse } from '@swc/core'
+import { ancestor } from 'swc-walk'
+import chalk from 'chalk'
+import ora from 'ora'
+import type { I18nextToolkitConfig } from './types'
+
+/**
+ * Runs the i18next linter to detect hardcoded strings and other potential issues.
+ *
+ * This function performs static analysis on source files to identify:
+ * - Hardcoded text strings in JSX elements
+ * - Hardcoded strings in JSX attributes (like alt text, titles, etc.)
+ * - Text that should be extracted for translation
+ *
+ * The linter respects configuration settings:
+ * - Uses the same input patterns as the extractor
+ * - Ignores content inside configured Trans components
+ * - Skips technical content like script/style tags
+ * - Identifies numeric values and interpolation syntax to avoid false positives
+ *
+ * @param config - The toolkit configuration with input patterns and component names
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   extract: {
+ *     input: ['src/**\/*.{ts,tsx}'],
+ *     transComponents: ['Trans', 'Translation']
+ *   }
+ * }
+ *
+ * await runLinter(config)
+ * // Outputs issues found or success message
+ * // Exits with code 1 if issues found, 0 if clean
+ * ```
+ */
+export async function runLinter (config: I18nextToolkitConfig) {
+  const spinner = ora('Analyzing source files...\n').start()
+
+  try {
+    const sourceFiles = await glob(config.extract.input)
+    let totalIssues = 0
+    const issuesByFile = new Map<string, HardcodedString[]>()
+
+    for (const file of sourceFiles) {
+      const code = await readFile(file, 'utf-8')
+      const ast = await parse(code, { syntax: 'typescript', tsx: true })
+      const hardcodedStrings = findHardcodedStrings(ast, code, config)
+
+      if (hardcodedStrings.length > 0) {
+        totalIssues += hardcodedStrings.length
+        issuesByFile.set(file, hardcodedStrings)
+      }
+    }
+
+    if (totalIssues > 0) {
+      spinner.fail(chalk.red.bold(`Linter found ${totalIssues} potential issues.`))
+
+      // Print detailed report after spinner fails
+      for (const [file, issues] of issuesByFile.entries()) {
+        console.log(chalk.yellow(`\n${file}`))
+        issues.forEach(({ text, line }) => {
+          console.log(`  ${chalk.gray(`${line}:`)} ${chalk.red('Error:')} Found hardcoded string: "${text}"`)
+        })
+      }
+      process.exit(1)
+    } else {
+      spinner.succeed(chalk.green.bold('No issues found.'))
+    }
+  } catch (error) {
+    spinner.fail(chalk.red('Linter failed to run.'))
+    console.error(error)
+    process.exit(1)
+  }
+}
+
+/**
+ * Represents a found hardcoded string with its location information.
+ */
+interface HardcodedString {
+  /** The hardcoded text content */
+  text: string;
+  /** Line number where the string was found */
+  line: number;
+}
+
+/**
+ * Analyzes an AST to find potentially hardcoded strings that should be translated.
+ *
+ * This function traverses the syntax tree looking for:
+ * 1. JSX text nodes with translatable content
+ * 2. String literals in JSX attributes that might need translation
+ *
+ * It applies several filters to reduce false positives:
+ * - Ignores content inside Trans components (already handled)
+ * - Skips script and style tag content (technical, not user-facing)
+ * - Filters out numeric values (usually not translatable)
+ * - Ignores interpolation syntax starting with `{{`
+ * - Only reports non-empty, trimmed strings
+ *
+ * @param ast - The parsed AST to analyze
+ * @param code - Original source code for line number calculation
+ * @param config - Configuration containing Trans component names
+ * @returns Array of found hardcoded strings with location info
+ *
+ * @example
+ * ```typescript
+ * const issues = findHardcodedStrings(ast, sourceCode, config)
+ * issues.forEach(issue => {
+ *   console.log(`Line ${issue.line}: "${issue.text}"`)
+ * })
+ * ```
+ */
+function findHardcodedStrings (ast: any, code: string, config: I18nextToolkitConfig): HardcodedString[] {
+  const issues: HardcodedString[] = []
+  const lineStarts: number[] = [0]
+  for (let i = 0; i < code.length; i++) {
+    if (code[i] === '\n') lineStarts.push(i + 1)
+  }
+
+  /**
+   * Converts a character position to a line number.
+   *
+   * @param pos - Character position in the source code
+   * @returns Line number (1-based)
+   */
+  const getLineNumber = (pos: number): number => {
+    let line = 1
+    for (let i = 0; i < lineStarts.length; i++) {
+      if (lineStarts[i] > pos) break
+      line = i + 1
+    }
+    return line
+  }
+
+  const transComponents = config.extract.transComponents || ['Trans']
+  const defaultIgnoredAttributes = ['className', 'key', 'id', 'style', 'href', 'i18nKey', 'defaults', 'type']
+  const customIgnoredAttributes = config.extract.ignoredAttributes || []
+  const ignoredAttributes = new Set([...defaultIgnoredAttributes, ...customIgnoredAttributes])
+
+  ancestor(ast, {
+    /**
+     * Processes JSX text nodes to identify hardcoded content.
+     *
+     * @param node - JSX text node
+     * @param ancestors - Array of ancestor nodes for context
+     */
+    JSXText (node: any, ancestors: any[]) {
+      const parent = ancestors[ancestors.length - 2]
+      const parentName = parent?.opening?.name?.value
+
+      if (parentName && (transComponents.includes(parentName) || parentName === 'script' || parentName === 'style')) {
+        return
+      }
+
+      const isIgnored = ancestors.some(ancestorNode => {
+        if (ancestorNode.type !== 'JSXElement') return false
+        const elementName = ancestorNode.opening?.name?.value
+        return transComponents.includes(elementName) || ['script', 'style', 'code'].includes(elementName)
+      })
+
+      if (isIgnored) return
+
+      const text = node.value.trim()
+      if (text && isNaN(Number(text)) && !text.startsWith('{{')) {
+        issues.push({ text, line: getLineNumber(node.span.start) })
+      }
+    },
+
+    /**
+     * Processes string literals in JSX attributes.
+     *
+     * @param node - String literal node
+     * @param ancestors - Array of ancestor nodes for context
+     */
+    StringLiteral (node: any, ancestors: any[]) {
+      const parent = ancestors[ancestors.length - 2]
+
+      // This check now uses the new combined Set
+      if (parent?.type === 'JSXAttribute' && !ignoredAttributes.has(parent.name.value)) {
+        const text = node.value.trim()
+        if (text && isNaN(Number(text))) {
+          issues.push({ text, line: getLineNumber(node.span.start) })
+        }
+      }
+    },
+  })
+  return issues
+}

package/src/locize.ts

@@ -0,0 +1,251 @@
+import { execa } from 'execa'
+import chalk from 'chalk'
+import ora from 'ora'
+import inquirer from 'inquirer'
+import { resolve } from 'node:path'
+import type { I18nextToolkitConfig } from './types'
+
+/**
+ * Verifies that the locize-cli tool is installed and accessible.
+ *
+ * @throws Exits the process with error code 1 if locize-cli is not found
+ *
+ * @example
+ * ```typescript
+ * await checkLocizeCliExists()
+ * // Continues execution if locize-cli is available
+ * // Otherwise exits with installation instructions
+ * ```
+ */
+async function checkLocizeCliExists (): Promise<void> {
+  try {
+    await execa('locize', ['--version'])
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      console.error(chalk.red('Error: `locize-cli` command not found.'))
+      console.log(chalk.yellow('Please install it globally to use the locize integration:'))
+      console.log(chalk.cyan('npm install -g locize-cli'))
+      process.exit(1)
+    }
+  }
+}
+
+/**
+ * Interactive setup wizard for configuring Locize credentials.
+ *
+ * This function guides users through setting up their Locize integration when
+ * configuration is missing or invalid. It:
+ * 1. Prompts for Project ID, API Key, and version
+ * 2. Validates required fields
+ * 3. Temporarily sets credentials for the current run
+ * 4. Provides security recommendations for storing credentials
+ * 5. Shows code examples for proper configuration
+ *
+ * @param config - Configuration object to update with new credentials
+ * @returns Promise resolving to the Locize configuration or undefined if setup was cancelled
+ *
+ * @example
+ * ```typescript
+ * const locizeConfig = await interactiveCredentialSetup(config)
+ * if (locizeConfig) {
+ *   // Proceed with sync using the new credentials
+ * }
+ * ```
+ */
+async function interactiveCredentialSetup (config: I18nextToolkitConfig): Promise<{ projectId?: string, apiKey?: string, version?: string } | undefined> {
+  console.log(chalk.yellow('\nLocize configuration is missing or invalid. Let\'s set it up!'))
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectId',
+      message: 'What is your locize Project ID? (Find this in your project settings on www.locize.app)',
+      validate: input => !!input || 'Project ID cannot be empty.',
+    },
+    {
+      type: 'password',
+      name: 'apiKey',
+      message: 'What is your locize API key? (Create or use one in your project settings > "API Keys")',
+      validate: input => !!input || 'API Key cannot be empty.',
+    },
+    {
+      type: 'input',
+      name: 'version',
+      message: 'What version do you want to sync with?',
+      default: 'latest',
+    },
+  ])
+
+  if (!answers.projectId) {
+    console.error(chalk.red('Project ID is required to continue.'))
+    return undefined
+  }
+
+  // Use the entered credentials for the current run
+  config.locize = {
+    projectId: answers.projectId,
+    apiKey: answers.apiKey,
+    version: answers.version,
+  }
+
+  const { save } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'save',
+    message: 'Would you like to see how to save these credentials for future use?',
+    default: true,
+  }])
+
+  if (save) {
+    const envSnippet = `
+# Add this to your .env file (and ensure .env is in your .gitignore!)
+LOCIZE_API_KEY=${answers.apiKey}
+`
+    const configSnippet = `
+  // Add this to your i18next.config.ts file
+  locize: {
+    projectId: '${answers.projectId}',
+    // For security, apiKey is best set via an environment variable
+    apiKey: process.env.LOCIZE_API_KEY,
+    version: '${answers.version}',
+  },`
+
+    console.log(chalk.cyan('\nGreat! For the best security, we recommend using environment variables for your API key.'))
+    console.log(chalk.bold('\nRecommended approach (.env file):'))
+    console.log(chalk.green(envSnippet))
+    console.log(chalk.bold('Then, in your i18next.config.ts:'))
+    console.log(chalk.green(configSnippet))
+  }
+
+  return config.locize
+}
+
+/**
+ * Converts CLI options and configuration into locize-cli command arguments.
+ *
+ * Maps toolkit configuration and CLI flags to the appropriate locize-cli arguments:
+ * - `updateValues` → `--update-values`
+ * - `sourceLanguageOnly` → `--reference-language-only`
+ * - `compareModificationTime` → `--compare-modification-time`
+ * - `dryRun` → `--dry`
+ *
+ * @param command - The locize command being executed
+ * @param cliOptions - CLI options passed to the command
+ * @param locizeConfig - Locize configuration from the config file
+ * @returns Array of command-line arguments
+ *
+ * @example
+ * ```typescript
+ * const args = cliOptionsToArgs('sync', { updateValues: true }, { dryRun: false })
+ * // Returns: ['--update-values', 'true']
+ * ```
+ */
+function cliOptionsToArgs (command: 'sync' | 'download' | 'migrate', cliOptions: any = {}, locizeConfig: any = {}) {
+  const commandArgs: string[] = []
+
+  // Pass-through options
+  if (command === 'sync') {
+    const updateValues = cliOptions.updateValues ?? locizeConfig.updateValues
+    if (updateValues) commandArgs.push('--update-values', 'true')
+    const srcLngOnly = cliOptions.srcLngOnly ?? locizeConfig.sourceLanguageOnly
+    if (srcLngOnly) commandArgs.push('--reference-language-only', 'true')
+    const compareMtime = cliOptions.compareMtime ?? locizeConfig.compareModificationTime
+    if (compareMtime) commandArgs.push('--compare-modification-time', 'true')
+    const dryRun = cliOptions.dryRun ?? locizeConfig.dryRun
+    if (dryRun) commandArgs.push('--dry', 'true')
+  }
+
+  return commandArgs
+}
+
+/**
+ * Executes a locize-cli command with proper error handling and credential management.
+ *
+ * This is the core function that:
+ * 1. Validates that locize-cli is installed
+ * 2. Builds command arguments from configuration and CLI options
+ * 3. Executes the locize command with proper credential handling
+ * 4. Provides interactive credential setup on authentication errors
+ * 5. Handles retries with new credentials
+ * 6. Reports success or failure with appropriate exit codes
+ *
+ * @param command - The locize command to execute ('sync', 'download', or 'migrate')
+ * @param config - The toolkit configuration with locize settings
+ * @param cliOptions - Additional options passed from CLI arguments
+ *
+ * @example
+ * ```typescript
+ * // Sync local files to Locize
+ * await runLocizeCommand('sync', config, { updateValues: true })
+ *
+ * // Download translations from Locize
+ * await runLocizeCommand('download', config)
+ *
+ * // Migrate local files to a new Locize project
+ * await runLocizeCommand('migrate', config)
+ * ```
+ */
+async function runLocizeCommand (command: 'sync' | 'download' | 'migrate', config: I18nextToolkitConfig, cliOptions: any = {}) {
+  await checkLocizeCliExists()
+
+  const spinner = ora(`Running 'locize ${command}'...\n`).start()
+
+  const locizeConfig = config.locize || {}
+  const { projectId, apiKey, version } = locizeConfig
+  let commandArgs: string[] = [command]
+
+  if (projectId) commandArgs.push('--project-id', projectId)
+  if (apiKey) commandArgs.push('--api-key', apiKey)
+  if (version) commandArgs.push('--ver', version)
+  // TODO: there might be more configurable locize-cli options in future
+
+  commandArgs.push(...cliOptionsToArgs(command, cliOptions, locizeConfig))
+
+  const basePath = resolve(process.cwd(), config.extract.output.split('/{{language}}/')[0])
+  commandArgs.push('--path', basePath)
+
+  try {
+    console.log(chalk.cyan(`\nRunning 'locize ${commandArgs.join(' ')}'...`))
+    const result = await execa('locize', commandArgs, { stdio: 'pipe' })
+    spinner.succeed(chalk.green(`'locize ${command}' completed successfully.`))
+    if (result?.stdout) console.log(result.stdout) // Print captured output on success
+  } catch (error: any) {
+    const stderr = error.stderr || ''
+    if (stderr.includes('missing required argument')) {
+      // Fallback to interactive setup
+      const newCredentials = await interactiveCredentialSetup(config)
+      if (newCredentials) {
+        // Retry the command with the new credentials
+        commandArgs = [command]
+        if (newCredentials.projectId) commandArgs.push('--project-id', newCredentials.projectId)
+        if (newCredentials.apiKey) commandArgs.push('--api-key', newCredentials.apiKey)
+        if (newCredentials.version) commandArgs.push('--ver', newCredentials.version)
+        // TODO: there might be more configurable locize-cli options in future
+        commandArgs.push(...cliOptionsToArgs(command, cliOptions, locizeConfig))
+        commandArgs.push('--path', basePath)
+        try {
+          spinner.start('Retrying with new credentials...') // Restart spinner
+          const result = await execa('locize', commandArgs, { stdio: 'pipe' })
+          spinner.succeed(chalk.green('Retry successful!'))
+          if (result?.stdout) console.log(result.stdout) // Print captured output on success
+        } catch (retryError: any) {
+          spinner.fail(chalk.red('Error during retry.'))
+          console.error(retryError.stderr || retryError.message)
+          process.exit(1)
+        }
+      } else {
+        spinner.fail('Operation cancelled.')
+        process.exit(1) // User aborted the prompt
+      }
+    } else {
+      // Handle other errors
+      spinner.fail(chalk.red(`Error executing 'locize ${command}'.`))
+      console.error(stderr || error.message)
+      process.exit(1)
+    }
+  }
+  console.log(chalk.green(`\n✅ 'locize ${command}' completed successfully.`))
+}
+
+export const runLocizeSync = (config: I18nextToolkitConfig, cliOptions?: any) => runLocizeCommand('sync', config, cliOptions)
+export const runLocizeDownload = (config: I18nextToolkitConfig, cliOptions?: any) => runLocizeCommand('download', config, cliOptions)
+export const runLocizeMigrate = (config: I18nextToolkitConfig, cliOptions?: any) => runLocizeCommand('migrate', config, cliOptions)

package/src/migrator.ts

@@ -0,0 +1,139 @@
+import { resolve } from 'node:path'
+import { writeFile, access } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Path to the legacy i18next-parser configuration file
+ */
+const oldConfigPath = resolve(process.cwd(), 'i18next-parser.config.js')
+
+/**
+ * Path where the new configuration file will be created
+ */
+const newConfigPath = resolve(process.cwd(), 'i18next.config.ts')
+
+/**
+ * List of possible new configuration file names that would prevent migration
+ */
+const POSSIBLE_NEW_CONFIGS = [
+  'i18next.config.ts',
+  'i18next.config.js',
+  'i18next.config.mjs',
+  'i18next.config.cjs',
+]
+
+/**
+ * Migrates a legacy i18next-parser.config.js configuration file to the new
+ * i18next-cli configuration format.
+ *
+ * This function:
+ * 1. Checks if a legacy config file exists
+ * 2. Prevents migration if any new config file already exists
+ * 3. Dynamically imports the old configuration
+ * 4. Maps old configuration properties to new format:
+ *    - `$LOCALE` → `{{language}}`
+ *    - `$NAMESPACE` → `{{namespace}}`
+ *    - Maps lexer functions and components
+ *    - Creates sensible defaults for new features
+ * 5. Generates a new TypeScript configuration file
+ * 6. Provides warnings for deprecated features
+ *
+ * @example
+ * ```typescript
+ * // Legacy config (i18next-parser.config.js):
+ * module.exports = {
+ *   locales: ['en', 'de'],
+ *   output: 'locales/$LOCALE/$NAMESPACE.json',
+ *   input: ['src/**\/*.js']
+ * }
+ *
+ * // After migration (i18next.config.ts):
+ * export default defineConfig({
+ *   locales: ['en', 'de'],
+ *   extract: {
+ *     input: ['src/**\/*.js'],
+ *     output: 'locales/{{language}}/{{namespace}}.json'
+ *   }
+ * })
+ * ```
+ */
+export async function runMigrator () {
+  console.log('Attempting to migrate legacy i18next-parser.config.js...')
+
+  try {
+    await access(oldConfigPath)
+  } catch (e) {
+    console.log('No i18next-parser.config.js found. Nothing to migrate.')
+    return
+  }
+
+  try {
+    await access(oldConfigPath)
+  } catch (e) {
+    console.log('No i18next-parser.config.js found. Nothing to migrate.')
+    return
+  }
+
+  // Check if ANY new config file already exists
+  for (const configFile of POSSIBLE_NEW_CONFIGS) {
+    try {
+      const fullPath = resolve(process.cwd(), configFile)
+      await access(fullPath)
+      console.warn(`Warning: A new configuration file already exists at "${configFile}". Migration skipped to avoid overwriting.`)
+      return
+    } catch (e) {
+      // File doesn't exist, which is good
+    }
+  }
+
+  // Dynamically import the CJS config file
+  const oldConfigUrl = pathToFileURL(oldConfigPath).href
+  const oldConfigModule = await import(oldConfigUrl)
+  const oldConfig = oldConfigModule.default
+
+  if (!oldConfig) {
+    console.error('Could not read the legacy config file.')
+    return
+  }
+
+  // --- Start Migration Logic ---
+  const newConfig = {
+    locales: oldConfig.locales || ['en'],
+    extract: {
+      input: oldConfig.input || 'src/**/*.{js,jsx,ts,tsx}',
+      output: (oldConfig.output || 'locales/$LOCALE/$NAMESPACE.json').replace('$LOCALE', '{{language}}').replace('$NAMESPACE', '{{namespace}}'),
+      defaultNS: oldConfig.defaultNamespace || 'translation',
+      keySeparator: oldConfig.keySeparator,
+      nsSeparator: oldConfig.namespaceSeparator,
+      contextSeparator: oldConfig.contextSeparator,
+      // A simple mapping for functions
+      functions: oldConfig.lexers?.js?.functions || ['t'],
+      transComponents: oldConfig.lexers?.js?.components || ['Trans'],
+    },
+    typesafe: {
+      input: 'locales/{{language}}/{{namespace}}.json', // Sensible default
+      output: 'src/types/i18next.d.ts', // Sensible default
+    },
+    sync: {
+      primaryLanguage: oldConfig.locales?.[0] || 'en',
+      secondaryLanguages: oldConfig.locales.filter((l: string) => l !== (oldConfig.locales?.[0] || 'en'))
+    },
+  }
+  // --- End Migration Logic ---
+
+  // Generate the new file content as a string
+  const newConfigFileContent = `
+import { defineConfig } from 'i18next-cli';
+
+export default defineConfig(${JSON.stringify(newConfig, null, 2)});
+`
+
+  await writeFile(newConfigPath, newConfigFileContent.trim())
+
+  console.log('✅ Success! Migration complete.')
+  console.log(`New configuration file created at: ${newConfigPath}`)
+  console.warn('\nPlease review the generated file and adjust paths for "typesafe.input" if necessary.')
+  if (oldConfig.keepRemoved) {
+    console.warn('Warning: The "keepRemoved" option is deprecated. Consider using the "preservePatterns" feature for dynamic keys.')
+  }
+}