i18next-cli 0.9.0

package/src/types.ts

@@ -0,0 +1,312 @@
+import type { Node } from '@swc/core'
+
+/**
+ * Main configuration interface for the i18next toolkit.
+ * Defines all available options for extraction, type generation, synchronization, and integrations.
+ *
+ * @example
+ * ```typescript
+ * const config: I18nextToolkitConfig = {
+ *   locales: ['en', 'de', 'fr'],
+ *   extract: {
+ *     input: ['src/**\/*.{ts,tsx}'],
+ *     output: 'locales/{{language}}/{{namespace}}.json',
+ *     functions: ['t', 'i18n.t'],
+ *     transComponents: ['Trans', 'Translation']
+ *   },
+ *   types: {
+ *     input: ['locales/en/*.json'],
+ *     output: 'src/types/i18next.d.ts'
+ *   }
+ * }
+ * ```
+ */
+export interface I18nextToolkitConfig {
+  /** Array of supported locale codes (e.g., ['en', 'de', 'fr']) */
+  locales: string[];
+
+  /** Configuration options for translation key extraction */
+  extract: {
+    /** Glob pattern(s) for source files to scan for translation keys */
+    input: string | string[];
+
+    /** Output path template with placeholders: {{language}} for locale, {{namespace}} for namespace */
+    output: string;
+
+    /** Default namespace when none is specified (default: 'translation') */
+    defaultNS?: string;
+
+    /** Separator for nested keys, or false for flat keys (default: '.') */
+    keySeparator?: string | false | null;
+
+    /** Separator between namespace and key, or false to disable (default: ':') */
+    nsSeparator?: string | false | null;
+
+    /** Separator for context variants (default: '_') */
+    contextSeparator?: string;
+
+    /** Separator for plural variants (default: '_') */
+    pluralSeparator?: string;
+
+    /** Function names to extract translation calls from (default: ['t']) */
+    functions?: string[];
+
+    /** JSX component names to extract translations from (default: ['Trans']) */
+    transComponents?: string[];
+
+    /** Hook function names that return translation functions (default: ['useTranslation']) */
+    useTranslationNames?: string[];
+
+    /** A list of JSX attribute names to ignore when linting for hardcoded strings. */
+    ignoredAttributes?: string[];
+
+    /** HTML tags to preserve in Trans component serialization (default: ['br', 'strong', 'i']) */
+    transKeepBasicHtmlNodesFor?: string[];
+
+    /** Glob patterns for keys to preserve even if not found in source (for dynamic keys) */
+    preservePatterns?: string[];
+
+    /** Whether to sort keys alphabetically in output files (default: true) */
+    sort?: boolean;
+
+    /** Number of spaces for JSON indentation (default: 2) */
+    indentation?: number;
+
+    /** Default value to use for missing translations in secondary languages */
+    defaultValue?: string;
+
+    /** Primary language that provides default values (default: first locale) */
+    primaryLanguage?: string;
+
+    /** Secondary languages that get empty values initially */
+    secondaryLanguages?: string[];
+  };
+
+  /** Configuration options for TypeScript type generation */
+  types?: {
+    /** Glob pattern(s) for translation files to generate types from */
+    input: string | string[];
+
+    /** Output path for the main TypeScript definition file */
+    output: string;
+
+    /** Enable type-safe selector API (boolean or 'optimize' for smaller types) */
+    enableSelector?: boolean | 'optimize';
+
+    /** Path for the separate resources interface file */
+    resourcesFile?: string;
+  };
+
+  /** Array of plugins to extend functionality */
+  plugins?: Plugin[];
+
+  /** Configuration for Locize integration */
+  locize?: {
+    /** Locize project ID */
+    projectId?: string;
+
+    /** Locize API key (recommended to use environment variables) */
+    apiKey?: string;
+
+    /** Version to sync with (default: 'latest') */
+    version?: string;
+
+    /** Whether to update existing translation values on Locize */
+    updateValues?: boolean;
+
+    /** Only sync the source language to Locize */
+    sourceLanguageOnly?: boolean;
+
+    /** Compare modification times when syncing */
+    compareModificationTime?: boolean;
+
+    /** Preview changes without making them */
+    dryRun?: boolean;
+  };
+}
+
+/**
+ * Plugin interface for extending the i18next toolkit functionality.
+ * Plugins can hook into various stages of the extraction process.
+ *
+ * @example
+ * ```typescript
+ * const myPlugin = (): Plugin => ({
+ *   name: 'my-custom-plugin',
+ *
+ *   setup: async () => {
+ *     console.log('Plugin initialized')
+ *   },
+ *
+ *   onLoad: (code, filePath) => {
+ *     // Transform code before parsing
+ *     return code.replace(/OLD_PATTERN/g, 'NEW_PATTERN')
+ *   },
+ *
+ *   onVisitNode: (node, context) => {
+ *     if (node.type === 'CallExpression') {
+ *       // Custom extraction logic
+ *       context.addKey({ key: 'custom.key', defaultValue: 'Custom Value' })
+ *     }
+ *   },
+ *
+ *   onEnd: async (allKeys) => {
+ *     console.log(`Found ${allKeys.size} total keys`)
+ *   }
+ * })
+ * ```
+ */
+export interface Plugin {
+  /** Unique name for the plugin */
+  name: string;
+
+  /**
+   * Hook called once at the beginning of the extraction process.
+   * Use for initialization tasks like setting up resources or validating configuration.
+   */
+  setup?: () => void | Promise<void>;
+
+  /**
+   * Hook called for each source file before it's parsed.
+   * Allows transformation of source code before AST generation.
+   *
+   * @param code - The source code content
+   * @param path - The file path being processed
+   * @returns The transformed code (or undefined to keep original)
+   */
+  onLoad?: (code: string, path: string) => string | Promise<string>;
+
+  /**
+   * Hook called for each AST node during traversal.
+   * Enables custom extraction logic by examining syntax nodes.
+   *
+   * @param node - The current AST node being visited
+   * @param context - Context object with helper methods
+   */
+  onVisitNode?: (node: Node, context: PluginContext) => void;
+
+  /**
+   * Hook called after all files have been processed.
+   * Useful for post-processing, validation, or reporting.
+   *
+   * @param keys - Final map of all extracted keys
+   */
+  onEnd?: (keys: Map<string, { key: string; defaultValue?: string }>) => void | Promise<void>;
+}
+
+/**
+ * Represents an extracted translation key with its metadata.
+ * Contains all information needed to generate translation files.
+ *
+ * @example
+ * ```typescript
+ * const extractedKey: ExtractedKey = {
+ *   key: 'user.profile.name',
+ *   defaultValue: 'Full Name',
+ *   ns: 'common',
+ *   hasCount: false
+ * }
+ * ```
+ */
+export interface ExtractedKey {
+  /** The translation key (may be nested with separators) */
+  key: string;
+
+  /** Default value to use in the primary language */
+  defaultValue?: string;
+
+  /** Namespace this key belongs to */
+  ns?: string;
+
+  /** Whether this key is used with pluralization (count parameter) */
+  hasCount?: boolean;
+}
+
+/**
+ * Result of processing translation files for a specific locale and namespace.
+ * Contains the generated translations and metadata about changes.
+ *
+ * @example
+ * ```typescript
+ * const result: TranslationResult = {
+ *   path: '/project/locales/en/common.json',
+ *   updated: true,
+ *   newTranslations: { button: { save: 'Save', cancel: 'Cancel' } },
+ *   existingTranslations: { button: { save: 'Save' } }
+ * }
+ * ```
+ */
+export interface TranslationResult {
+  /** Full file system path where the translation file will be written */
+  path: string;
+
+  /** Whether the file content changed and needs to be written */
+  updated: boolean;
+
+  /** The new translation object to be written to the file */
+  newTranslations: Record<string, any>;
+
+  /** The existing translation object that was read from the file */
+  existingTranslations: Record<string, any>;
+}
+
+/**
+ * Logger interface for consistent output formatting across the toolkit.
+ * Implementations can customize how messages are displayed or stored.
+ *
+ * @example
+ * ```typescript
+ * class FileLogger implements Logger {
+ *   info(message: string) { fs.appendFileSync('info.log', message) }
+ *   warn(message: string) { fs.appendFileSync('warn.log', message) }
+ *   error(message: string) { fs.appendFileSync('error.log', message) }
+ * }
+ * ```
+ */
+export interface Logger {
+  /**
+   * Logs an informational message.
+   * @param message - The message to log
+   */
+  info(message: string): void;
+
+  /**
+   * Logs a warning message.
+   * @param message - The warning message to log
+   */
+  warn(message: string): void;
+
+  /**
+   * Logs an error message.
+   * @param message - The error message to log
+   */
+  error(message: string): void;
+}
+
+/**
+ * Context object provided to plugins during AST traversal.
+ * Provides helper methods for plugins to interact with the extraction process.
+ *
+ * @example
+ * ```typescript
+ * // Inside a plugin's onVisitNode hook:
+ * onVisitNode(node, context) {
+ *   if (isCustomTranslationCall(node)) {
+ *     context.addKey({
+ *       key: extractKeyFromNode(node),
+ *       defaultValue: extractDefaultFromNode(node),
+ *       ns: 'custom'
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export interface PluginContext {
+  /**
+   * Adds a translation key to the extraction results.
+   * Keys are automatically deduplicated by their namespace:key combination.
+   *
+   * @param keyInfo - The extracted key information
+   */
+  addKey: (keyInfo: ExtractedKey) => void;
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,81 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * Ensures that the directory for a given file path exists.
+ * Creates all necessary parent directories recursively if they don't exist.
+ *
+ * @param filePath - The file path for which to ensure the directory exists
+ *
+ * @example
+ * ```typescript
+ * await ensureDirectoryExists('/path/to/nested/file.json')
+ * // Creates /path/to/nested/ directory if it doesn't exist
+ * ```
+ */
+export async function ensureDirectoryExists (filePath: string): Promise<void> {
+  const dir = dirname(filePath)
+  await mkdir(dir, { recursive: true })
+}
+
+/**
+ * Reads a file asynchronously and returns its content as a UTF-8 string.
+ *
+ * @param filePath - The path to the file to read
+ * @returns Promise resolving to the file content as a string
+ *
+ * @example
+ * ```typescript
+ * const content = await readFileAsync('./config.json')
+ * const config = JSON.parse(content)
+ * ```
+ */
+export async function readFileAsync (filePath: string): Promise<string> {
+  return await readFile(filePath, 'utf-8')
+}
+
+/**
+ * Writes data to a file asynchronously.
+ *
+ * @param filePath - The path where to write the file
+ * @param data - The string data to write to the file
+ *
+ * @example
+ * ```typescript
+ * const jsonData = JSON.stringify({ key: 'value' }, null, 2)
+ * await writeFileAsync('./output.json', jsonData)
+ * ```
+ */
+export async function writeFileAsync (filePath: string, data: string): Promise<void> {
+  await writeFile(filePath, data)
+}
+
+/**
+ * Generates a file path by replacing template placeholders with actual values.
+ * Supports both legacy and modern placeholder formats for language and namespace.
+ *
+ * @param template - The template string containing placeholders
+ * @param locale - The locale/language code to substitute
+ * @param namespace - The namespace to substitute
+ * @returns The resolved file path with placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * // Modern format
+ * getOutputPath('locales/{{language}}/{{namespace}}.json', 'de', 'validation')
+ * // Returns: 'locales/de/validation.json'
+ *
+ * // Legacy format (also supported)
+ * getOutputPath('locales/{{lng}}/{{ns}}.json', 'en', 'common')
+ * // Returns: 'locales/en/common.json'
+ * ```
+ */
+export function getOutputPath (
+  template: string,
+  locale: string,
+  namespace: string
+): string {
+  return template
+    .replace('{{language}}', locale).replace('{{lng}}', locale)
+    .replace('{{namespace}}', namespace).replace('{{ns}}', namespace)
+}

package/src/utils/logger.ts

@@ -0,0 +1,36 @@
+import type { Logger } from '../types'
+
+/**
+ * Default console-based logger implementation for the i18next toolkit.
+ * Provides basic logging functionality with different severity levels.
+ *
+ * @example
+ * ```typescript
+ * const logger = new ConsoleLogger()
+ * logger.info('Extraction started')
+ * logger.warn('Deprecated configuration option used')
+ * logger.error('Failed to parse file')
+ * ```
+ */
+export class ConsoleLogger implements Logger {
+  /**
+   * Logs an informational message to the console.
+   *
+   * @param message - The message to log
+   */
+  info (message: string): void { console.log(message) }
+
+  /**
+   * Logs a warning message to the console.
+   *
+   * @param message - The warning message to log
+   */
+  warn (message: string): void { console.warn(message) }
+
+  /**
+   * Logs an error message to the console.
+   *
+   * @param message - The error message to log
+   */
+  error (message: string): void { console.error(message) }
+}

package/src/utils/nested-object.ts

@@ -0,0 +1,113 @@
+/**
+ * Sets a nested value in an object using a key path and separator.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The target object to modify
+ * @param path - The key path (e.g., 'user.profile.name')
+ * @param value - The value to set
+ * @param keySeparator - The separator to use for splitting the path, or false for flat keys
+ *
+ * @example
+ * ```typescript
+ * const obj = {}
+ * setNestedValue(obj, 'user.profile.name', 'John', '.')
+ * // Result: { user: { profile: { name: 'John' } } }
+ *
+ * // With flat keys
+ * setNestedValue(obj, 'user.name', 'Jane', false)
+ * // Result: { 'user.name': 'Jane' }
+ * ```
+ */
+export function setNestedValue (
+  obj: Record<string, any>,
+  path: string,
+  value: any,
+  keySeparator: string | false
+): void {
+  if (keySeparator === false) {
+    obj[path] = value
+    return
+  }
+  const keys = path.split(keySeparator)
+  keys.reduce((acc, key, index) => {
+    if (index === keys.length - 1) {
+      acc[key] = value
+    } else {
+      acc[key] = acc[key] || {}
+    }
+    return acc[key]
+  }, obj)
+}
+
+/**
+ * Retrieves a nested value from an object using a key path and separator.
+ *
+ * @param obj - The object to search in
+ * @param path - The key path (e.g., 'user.profile.name')
+ * @param keySeparator - The separator to use for splitting the path, or false for flat keys
+ * @returns The found value or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const obj = { user: { profile: { name: 'John' } } }
+ * const name = getNestedValue(obj, 'user.profile.name', '.')
+ * // Returns: 'John'
+ *
+ * // With flat keys
+ * const flatObj = { 'user.name': 'Jane' }
+ * const name = getNestedValue(flatObj, 'user.name', false)
+ * // Returns: 'Jane'
+ * ```
+ */
+export function getNestedValue (
+  obj: Record<string, any>,
+  path: string,
+  keySeparator: string | false
+): any {
+  if (keySeparator === false) {
+    return obj[path]
+  }
+  return path.split(keySeparator).reduce((acc, key) => acc && acc[key], obj)
+}
+
+/**
+ * Extracts all nested keys from an object, optionally with a prefix.
+ * Recursively traverses the object structure to build a flat list of key paths.
+ *
+ * @param obj - The object to extract keys from
+ * @param keySeparator - The separator to use for joining keys, or false for flat keys
+ * @param prefix - Optional prefix to prepend to all keys
+ * @returns Array of all nested key paths
+ *
+ * @example
+ * ```typescript
+ * const obj = {
+ *   user: {
+ *     profile: { name: 'John', age: 30 },
+ *     settings: { theme: 'dark' }
+ *   }
+ * }
+ *
+ * const keys = getNestedKeys(obj, '.')
+ * // Returns: ['user.profile.name', 'user.profile.age', 'user.settings.theme']
+ *
+ * // With flat keys
+ * const flatObj = { 'user.name': 'Jane', 'user.age': 25 }
+ * const flatKeys = getNestedKeys(flatObj, false)
+ * // Returns: ['user.name', 'user.age']
+ * ```
+ */
+export function getNestedKeys (obj: object, keySeparator: string | false, prefix = ''): string[] {
+  if (keySeparator === false) {
+    return Object.keys(obj)
+  }
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    const newKey = prefix ? `${prefix}${keySeparator}${key}` : key
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      acc.push(...getNestedKeys(value, keySeparator, newKey))
+    } else {
+      acc.push(newKey)
+    }
+    return acc
+  }, [] as string[])
+}

package/src/utils/validation.ts

@@ -0,0 +1,69 @@
+import type { I18nextToolkitConfig } from '../types'
+
+/**
+ * Validates the extractor configuration to ensure required fields are present and properly formatted.
+ *
+ * This function performs the following validations:
+ * - Ensures extract.input is specified and non-empty
+ * - Ensures extract.output is specified
+ * - Ensures locales array is specified and non-empty
+ * - Ensures extract.output contains the required {{language}} placeholder
+ *
+ * @param config - The i18next toolkit configuration object to validate
+ *
+ * @throws {ExtractorError} When any validation rule fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateExtractorConfig(config)
+ *   console.log('Configuration is valid')
+ * } catch (error) {
+ *   console.error('Invalid configuration:', error.message)
+ * }
+ * ```
+ */
+export function validateExtractorConfig (config: I18nextToolkitConfig): void {
+  if (!config.extract.input?.length) {
+    throw new ExtractorError('extract.input must be specified and non-empty')
+  }
+
+  if (!config.extract.output) {
+    throw new ExtractorError('extract.output must be specified')
+  }
+
+  if (!config.locales?.length) {
+    throw new ExtractorError('locales must be specified and non-empty')
+  }
+
+  if (!config.extract.output.includes('{{language}}') && !config.extract.output.includes('{{lng}}')) {
+    throw new ExtractorError('extract.output must contain {{language}} placeholder')
+  }
+}
+
+/**
+ * Custom error class for extraction-related errors.
+ * Provides additional context like file path and underlying cause.
+ *
+ * @example
+ * ```typescript
+ * throw new ExtractorError('Failed to parse file', 'src/component.tsx', syntaxError)
+ * ```
+ */
+export class ExtractorError extends Error {
+  /**
+   * Creates a new ExtractorError with optional file context and cause.
+   *
+   * @param message - The error message
+   * @param file - Optional file path where the error occurred
+   * @param cause - Optional underlying error that caused this error
+   */
+  constructor (
+    message: string,
+    public readonly file?: string,
+    public readonly cause?: Error
+  ) {
+    super(file ? `${message} in file ${file}` : message)
+    this.name = 'ExtractorError'
+  }
+}

package/tryme.js

@@ -0,0 +1,8 @@
+import { locize } from './dist/esm/index.js'
+locize.runLocizeSync({
+  extract: {
+    output: 'tmp-test'
+  }
+}, {
+  dryRun: true
+})