i18next-cli 0.9.0

package/src/status.ts

@@ -0,0 +1,192 @@
+import chalk from 'chalk'
+import ora, { Ora } from 'ora'
+import { resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { findKeys } from './extractor/core/key-finder'
+import { getNestedKeys, getNestedValue } from './utils/nested-object'
+import type { I18nextToolkitConfig, ExtractedKey } from './types'
+import { getOutputPath } from './utils/file-utils'
+
+interface StatusOptions {
+  detail?: string;
+}
+
+/**
+ * Runs a health check on the project's i18next translations and displays a status report.
+ *
+ * This command provides a high-level overview of the localization status by:
+ * 1. Extracting all keys from the source code using the core extractor.
+ * 2. Reading all existing translation files for each locale.
+ * 3. Calculating the translation completeness for each secondary language against the primary.
+ * 4. Displaying a formatted report with key counts, locales, and progress bars.
+ * 5. Serving as a value-driven funnel to introduce the locize commercial service.
+ *
+ * @param config - The i18next toolkit configuration object.
+ * @param options Options object, may contain a `detail` property with a locale string.
+ */
+export async function runStatus (config: I18nextToolkitConfig, options: StatusOptions = {}) {
+  const spinner = ora('Analyzing project localization status...\n').start()
+  try {
+    if (options.detail) {
+      await displayDetailedStatus(config, options.detail, spinner)
+    } else {
+      await displaySummaryStatus(config, spinner)
+    }
+  } catch (error) {
+    spinner.fail('Failed to generate status report.')
+    console.error(error)
+  }
+}
+
+/**
+ * Displays a detailed, key-by-key translation status for a specific locale,
+ * grouped by namespace.
+ * @param config The toolkit configuration.
+ * @param locale The locale to display the detailed status for.
+ * @internal
+ */
+async function displayDetailedStatus (config: I18nextToolkitConfig, locale: string, spinner: Ora) {
+  const { primaryLanguage, keySeparator = '.', defaultNS = 'translation' } = config.extract
+
+  if (!config.locales.includes(locale)) {
+    console.error(chalk.red(`Error: Locale "${locale}" is not defined in your configuration.`))
+    return
+  }
+  if (locale === primaryLanguage) {
+    console.log(chalk.yellow(`Locale "${locale}" is the primary language, so all keys are considered present.`))
+    return
+  }
+
+  console.log(`Analyzing detailed status for locale: ${chalk.bold.cyan(locale)}...`)
+
+  const allExtractedKeys = await findKeys(config)
+
+  spinner.succeed('Analysis complete.')
+
+  if (allExtractedKeys.size === 0) {
+    console.log(chalk.green('No keys found in source code.'))
+    return
+  }
+
+  // Group keys by namespace to read the correct files
+  const keysByNs = new Map<string, ExtractedKey[]>()
+  for (const key of allExtractedKeys.values()) {
+    const ns = key.ns || defaultNS
+    if (!keysByNs.has(ns)) keysByNs.set(ns, [])
+    keysByNs.get(ns)!.push(key)
+  }
+
+  const translationsByNs = new Map<string, Record<string, any>>()
+  for (const ns of keysByNs.keys()) {
+    const langFilePath = getOutputPath(config.extract.output, locale, ns)
+    try {
+      const content = await readFile(resolve(process.cwd(), langFilePath), 'utf-8')
+      translationsByNs.set(ns, JSON.parse(content))
+    } catch {
+      translationsByNs.set(ns, {}) // File not found, treat as empty
+    }
+  }
+
+  let missingCount = 0
+  console.log(chalk.bold(`\nKey Status for "${locale}":`))
+
+  // 1. Get and sort the namespace names alphabetically
+  const sortedNamespaces = Array.from(keysByNs.keys()).sort()
+
+  // 2. Loop through each namespace
+  for (const ns of sortedNamespaces) {
+    console.log(chalk.cyan.bold(`\nNamespace: ${ns}`))
+
+    const keysForNs = keysByNs.get(ns) || []
+    const sortedKeysForNs = keysForNs.sort((a, b) => a.key.localeCompare(b.key))
+    const translations = translationsByNs.get(ns) || {}
+
+    // 3. Loop through the keys within the current namespace
+    for (const { key } of sortedKeysForNs) {
+      const value = getNestedValue(translations, key, keySeparator ?? '.')
+
+      if (value) {
+        console.log(`  ${chalk.green('✓')} ${key}`)
+      } else {
+        missingCount++
+        console.log(`  ${chalk.red('✗')} ${key}`)
+      }
+    }
+  }
+
+  if (missingCount > 0) {
+    console.log(chalk.yellow.bold(`\n\nSummary: Found ${missingCount} missing translations for "${locale}".`))
+  } else {
+    console.log(chalk.green.bold(`\n\nSummary: 🎉 All ${allExtractedKeys.size} keys are translated for "${locale}".`))
+  }
+}
+
+/**
+ * Displays a high-level summary report of translation progress for all locales.
+ * @param config The toolkit configuration.
+ * @internal
+ */
+async function displaySummaryStatus (config: I18nextToolkitConfig, spinner: Ora) {
+  console.log('Analyzing project localization status...')
+
+  const allExtractedKeys = await findKeys(config)
+  const totalKeys = allExtractedKeys.size
+
+  const { primaryLanguage, keySeparator = '.', defaultNS = 'translation' } = config.extract
+  const secondaryLanguages = config.locales.filter(l => l !== primaryLanguage)
+
+  const allNamespaces = new Set<string>(
+    Array.from(allExtractedKeys.values()).map(k => k.ns || defaultNS)
+  )
+
+  spinner.succeed('Analysis complete.')
+
+  console.log(chalk.cyan.bold('\ni18next Project Status'))
+  console.log('------------------------')
+  console.log(`🔑 Keys Found:         ${chalk.bold(totalKeys)}`)
+  console.log(`🌍 Locales:            ${chalk.bold(config.locales.join(', '))}`)
+  console.log(`✅ Primary Language:   ${chalk.bold(primaryLanguage)}`)
+  console.log('\nTranslation Progress:')
+
+  for (const lang of secondaryLanguages) {
+    let translatedKeysCount = 0
+
+    for (const ns of allNamespaces) {
+      const langFilePath = getOutputPath(config.extract.output, lang, ns)
+      try {
+        const content = await readFile(resolve(process.cwd(), langFilePath), 'utf-8')
+        const translations = JSON.parse(content)
+        const translatedKeysInFile = getNestedKeys(translations, keySeparator ?? '.')
+
+        const countForNs = translatedKeysInFile.filter(k => {
+          const value = getNestedValue(translations, k, keySeparator ?? '.')
+          // A key is counted if it has a non-empty value AND it was extracted from the source for this namespace
+          return !!value && allExtractedKeys.has(`${ns}:${k}`)
+        }).length
+        translatedKeysCount += countForNs
+      } catch {
+        // File not found for this namespace, so its contribution to the count is 0
+      }
+    }
+
+    const percentage = totalKeys > 0 ? Math.round((translatedKeysCount / totalKeys) * 100) : 100
+    const progressBar = generateProgressBar(percentage)
+    console.log(`- ${lang}: ${progressBar} ${percentage}% (${translatedKeysCount}/${totalKeys} keys)`)
+  }
+
+  console.log(chalk.yellow.bold('\n✨ Take your localization to the next level!'))
+  console.log('Manage translations with your team in the cloud with locize => https://www.locize.com/docs/getting-started')
+  console.log(`Run ${chalk.cyan('npx i18next-cli locize-migrate')} to get started.`)
+}
+
+/**
+ * Generates a simple text-based progress bar.
+ * @param percentage - The percentage to display (0-100).
+ * @internal
+ */
+function generateProgressBar (percentage: number): string {
+  const totalBars = 20
+  const filledBars = Math.round((percentage / 100) * totalBars)
+  const emptyBars = totalBars - filledBars
+  return `[${chalk.green(''.padStart(filledBars, '■'))}${''.padStart(emptyBars, '□')}]`
+}

package/src/syncer.ts

@@ -0,0 +1,114 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { resolve, dirname } from 'path'
+import chalk from 'chalk'
+import ora from 'ora'
+import type { I18nextToolkitConfig } from './types'
+import { getNestedKeys, getNestedValue, setNestedValue } from './utils/nested-object'
+import { getOutputPath } from './utils/file-utils'
+
+/**
+ * Synchronizes translation files across different locales by ensuring all secondary
+ * language files contain the same keys as the primary language file.
+ *
+ * This function:
+ * 1. Reads the primary language translation file
+ * 2. Extracts all translation keys from the primary file
+ * 3. For each secondary language:
+ *    - Preserves existing translations
+ *    - Adds missing keys with empty values or configured default
+ *    - Removes keys that no longer exist in primary
+ * 4. Only writes files that have changes
+ *
+ * @param config - The i18next toolkit configuration object
+ *
+ * @example
+ * ```typescript
+ * // Configuration
+ * const config = {
+ *   locales: ['en', 'de', 'fr'],
+ *   extract: {
+ *     output: 'locales/{{language}}/{{namespace}}.json',
+ *     defaultNS: 'translation'
+ *     defaultValue: '[MISSING]'
+ *   }
+ * }
+ *
+ * await runSyncer(config)
+ * ```
+ */
+export async function runSyncer (config: I18nextToolkitConfig) {
+  const spinner = ora('Running i18next locale synchronizer...\n').start()
+
+  config.extract.primaryLanguage ||= config.locales[0] || 'en'
+  const { primaryLanguage } = config.extract
+  const secondaryLanguages = config.locales.filter(l => l !== primaryLanguage)
+  const keySeparator = config.extract.keySeparator ?? '.'
+
+  const logMessages: string[] = []
+  let wasAnythingSynced = false
+
+  // Assume sync operates on the default namespace for simplicity
+  const defaultNS = config.extract.defaultNS ?? 'translation'
+
+  // 1. Get all keys from the primary language file
+  const primaryPath = getOutputPath(config.extract.output, primaryLanguage, defaultNS)
+
+  const fullPrimaryPath = resolve(process.cwd(), primaryPath)
+
+  let primaryTranslations: Record<string, any>
+  try {
+    const primaryContent = await readFile(fullPrimaryPath, 'utf-8')
+    primaryTranslations = JSON.parse(primaryContent)
+  } catch (e) {
+    console.error(`Primary language file not found at ${primaryPath}. Cannot sync.`)
+    return
+  }
+
+  const primaryKeys = getNestedKeys(primaryTranslations, keySeparator)
+
+  // 2. Iterate through secondary languages and sync them
+  for (const lang of secondaryLanguages) {
+    const secondaryPath = getOutputPath(config.extract.output, lang, defaultNS)
+    const fullSecondaryPath = resolve(process.cwd(), secondaryPath)
+
+    let secondaryTranslations: Record<string, any> = {}
+    let oldContent = ''
+    try {
+      oldContent = await readFile(fullSecondaryPath, 'utf-8')
+      secondaryTranslations = JSON.parse(oldContent)
+    } catch (e) { /* File doesn't exist, will be created */ }
+
+    const newSecondaryTranslations: Record<string, any> = {}
+
+    // Rebuild the secondary file based on the primary file's keys
+    for (const key of primaryKeys) {
+      const existingValue = getNestedValue(secondaryTranslations, key, keySeparator)
+      // If value exists in old file, keep it. Otherwise, add as empty string.
+      const valueToSet = existingValue ?? (config.extract?.defaultValue || '')
+      setNestedValue(newSecondaryTranslations, key, valueToSet, keySeparator)
+    }
+
+    const indentation = config.extract.indentation ?? 2
+    const newContent = JSON.stringify(newSecondaryTranslations, null, indentation)
+
+    if (newContent !== oldContent) {
+      wasAnythingSynced = true
+      await mkdir(dirname(fullSecondaryPath), { recursive: true })
+      await writeFile(fullSecondaryPath, newContent)
+      logMessages.push(`  ${chalk.green('✓')} Synchronized: ${secondaryPath}`)
+    } else {
+      logMessages.push(`  ${chalk.gray('-')} Already in sync: ${secondaryPath}`)
+    }
+  }
+
+  spinner.succeed(chalk.bold('Synchronization complete!'))
+  logMessages.forEach(msg => console.log(msg))
+
+  if (wasAnythingSynced) {
+    console.log(chalk.green.bold('\n✅ Sync complete.'))
+    console.log(chalk.yellow('🚀 Ready to collaborate with translators? Move your files to the cloud.'))
+    console.log(`   Get started with the official TMS for i18next: ${chalk.cyan('npx i18next-cli locize-migrate')}`)
+  } else {
+    console.log(chalk.green.bold('\n✅ All locales are already in sync.'))
+  }
+}

package/src/types-generator.ts

@@ -0,0 +1,116 @@
+import { mergeResourcesAsInterface } from 'i18next-resources-for-ts'
+import { glob } from 'glob'
+import ora from 'ora'
+import chalk from 'chalk'
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises'
+import { basename, extname, resolve, dirname, join, relative } from 'node:path'
+import type { I18nextToolkitConfig } from './types'
+
+/**
+ * Represents a translation resource with its namespace name and content
+ */
+interface Resource {
+  /** The namespace name (filename without extension) */
+  name: string;
+  /** The parsed JSON resources object */
+  resources: object;
+}
+
+/**
+ * Generates TypeScript type definitions for i18next translations.
+ *
+ * This function:
+ * 1. Reads translation files based on the input glob patterns
+ * 2. Generates TypeScript interfaces using i18next-resources-for-ts
+ * 3. Creates separate resources.d.ts and main i18next.d.ts files
+ * 4. Handles namespace detection from filenames
+ * 5. Supports type-safe selector API when enabled
+ *
+ * @param config - The i18next toolkit configuration object
+ *
+ * @example
+ * ```typescript
+ * // Configuration
+ * const config = {
+ *   types: {
+ *     input: ['locales/en/*.json'],
+ *     output: 'src/types/i18next.d.ts',
+ *     enableSelector: true
+ *   }
+ * }
+ *
+ * await runTypesGenerator(config)
+ * ```
+ */
+export async function runTypesGenerator (config: I18nextToolkitConfig) {
+  const spinner = ora('Generating TypeScript types for translations...\n').start()
+
+  try {
+    if (!config.types) config.types = { input: ['locales/en/*.json'], output: 'src/types/i18next.d.ts' }
+    if (config.types.input === undefined) config.types.input = ['locales/en/*.json']
+    if (!config.types.output) config.types.output = 'src/types/i18next.d.ts'
+    if (!config.types.resourcesFile) config.types.resourcesFile = join(dirname(config.types?.output), 'resources.d.ts')
+
+    if (!config.types?.input || config.types?.input.length < 0) {
+      console.log('No input defined!')
+      return
+    }
+
+    const resourceFiles = await glob(config.types?.input || [], {
+      cwd: process.cwd(),
+    })
+
+    const resources: Resource[] = []
+
+    for (const file of resourceFiles) {
+      const namespace = basename(file, extname(file))
+      const content = await readFile(file, 'utf-8')
+      const parsedContent = JSON.parse(content)
+      resources.push({ name: namespace, resources: parsedContent })
+    }
+
+    const logMessages: string[] = []
+
+    const enableSelector = config.types?.enableSelector || false
+    const interfaceDefinition = mergeResourcesAsInterface(resources, { optimize: !!enableSelector })
+    const outputPath = resolve(process.cwd(), config.types?.output || '')
+    const resourcesOutputPath = resolve(process.cwd(), config.types.resourcesFile)
+    await mkdir(dirname(resourcesOutputPath), { recursive: true })
+    await writeFile(resourcesOutputPath, interfaceDefinition)
+    logMessages.push(`  ${chalk.green('✓')} Resources interface written to ${config.types.resourcesFile}`)
+
+    let outputPathExists
+    try {
+      await access(outputPath)
+      outputPathExists = true
+    } catch (e) {
+      outputPathExists = false
+    }
+
+    if (!outputPathExists) {
+    // The main output file will now import from the resources file
+      const importPath = relative(dirname(outputPath), resourcesOutputPath)
+        .replace(/\\/g, '/').replace(/\.d\.ts$/, '') // Make it a valid module path
+
+      const fileContent = `// This file is automatically generated by i18next-cli. Do not edit manually.
+import Resources from './${importPath}';
+
+declare module 'i18next' {
+  interface CustomTypeOptions {
+    enableSelector: ${typeof enableSelector === 'string' ? `"${enableSelector}"` : enableSelector};
+    defaultNS: '${config.extract.defaultNS || 'translation'}';
+    resources: Resources;
+  }
+}`
+      await mkdir(dirname(outputPath), { recursive: true })
+      await writeFile(outputPath, fileContent)
+      logMessages.push(`  ${chalk.green('✓')} TypeScript definitions written to ${config.types.output || ''}`)
+
+      spinner.succeed(chalk.bold('TypeScript definitions generated successfully.'))
+      logMessages.forEach(msg => console.log(msg))
+    }
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to generate TypeScript definitions.'))
+    console.error(error)
+  }
+}