i18next-cli 1.46.3 → 1.47.0

package/README.md

@@ -247,6 +247,163 @@ Analyzes your source code for internationalization issues like hardcoded strings
 npx i18next-cli lint
 ```
 
+### `instrument`
+
+Scans your source code for hardcoded user-facing strings and instruments them with i18next translation calls. This is useful for adding i18next instrumentation to an existing codebase that wasn't built with internationalization in mind.
+
+> **⚠️ First-Step Tool:** The `instrument` command uses heuristic-based detection and is designed as a **first pass** to identify and suggest transformation candidates. It will **not catch 100% of cases**, and you should expect both false positives and false negatives. Always review the suggested transformations carefully before committing them to your codebase. Think of it as an intelligent code assistant, not an automated compiler.
+
+```bash
+npx i18next-cli instrument
+```
+
+**Options:**
+- `--dry-run`: Preview changes without writing files to disk
+- `--interactive`: Prompt for approval of each candidate string
+- `--namespace <ns>`: Target a specific namespace for extracted keys
+- `-q, --quiet`: Suppress spinner and output
+
+**What it transforms:**
+
+The `instrument` command detects four types of transformations:
+
+1. **Simple string → `t()` call:**
+   ```javascript
+   // Before
+   const msg = 'Welcome back';
+   
+   // After
+   const msg = t('welcomeBack', 'Welcome back');
+   ```
+
+2. **Template literal (static only) → `t()` call:**
+   ```javascript
+   // Before
+   const msg = `Welcome back`;
+   
+   // After
+   const msg = t('welcomeBack', 'Welcome back');
+   ```
+   > Template literals with interpolation (e.g. `` `Hello ${name}` ``) are skipped — they require manual wrapping.
+
+3. **JSX text → JSX expression with `t()`:**
+   ```jsx
+   // Before
+   <h1>Welcome back</h1>
+   
+   // After
+   <h1>{t('welcomeBack', 'Welcome back')}</h1>
+   ```
+
+4. **JSX mixed content → `<Trans>` component:**
+   ```jsx
+   // Before
+   <p>Click <a href="/docs">here</a> to continue</p>
+   
+   // After
+   <p><Trans i18nKey="clickHereLabel">Click <a href="/docs">here</a> to continue</Trans></p>
+   ```
+
+**Namespace targeting:**
+
+Use `--namespace <ns>` to direct extracted keys into a specific namespace. When a non-default namespace is specified:
+- React components use `useTranslation('<ns>')` with clean keys
+- Non-component code uses `i18next.t('key', 'default', { ns: '<ns>' })`
+- In `--interactive` mode you are prompted for the target namespace
+
+```bash
+npx i18next-cli instrument --namespace common
+```
+
+**Custom scorer hook:**
+
+Override the built-in confidence heuristic via `extract.instrumentScorer` in your config. The function receives each candidate string and its context, and can:
+- Return a number (0–1) to override the confidence score
+- Return `null` to force-skip the candidate
+- Return `undefined` to fall back to the built-in heuristic
+
+```typescript
+export default defineConfig({
+  // ...
+  extract: {
+    // ...
+    instrumentScorer: (content, { file, code, beforeContext, afterContext }) => {
+      // Skip strings that belong to your analytics domain
+      if (content.startsWith('track_')) return null;
+      // Boost strings in your UI layer
+      if (file.includes('/components/')) return 0.95;
+      // Fall back to built-in detection for everything else
+      return undefined;
+    }
+  }
+});
+```
+
+**What it skips (by design):**
+
+The instrumenter uses confidence heuristics to avoid transforming:
+- Test files (`*.test.*`, `*.spec.*`)
+- Empty strings and single characters
+- Pure numbers and numeric IDs
+- URL strings and file paths
+- CSS class names and technical identifiers
+- Developer-facing error codes (all-caps patterns like `ERROR_NOT_FOUND`)
+- `console.log/warn/error` arguments
+- HTML attribute values that appear technical
+- Template literals with only expressions (no static text)
+- Strings already inside `t()` calls or `<Trans>` components
+
+**Auto-injection:**
+
+When transformations are applied, the command automatically:
+- Injects `import { useTranslation } from 'react-i18next'` in React files (or `import i18next from 'i18next'` for non-React files)
+- Injects `const { t } = useTranslation()` into each React function component that contains transformed strings
+- Detects the project's framework from `package.json` dependencies (React, Next.js, Vue, etc.)
+- Uses `useTranslation()` hook style `t()` inside React components, or `i18next.t()` for utility / non-component code
+- Generates an `i18n.ts` (or `i18n.js` for JS-only projects) initialization file if none exists, pre-configured with [`i18next-resources-to-backend`](https://github.com/i18next/i18next-resources-to-backend) to lazy-load your translation files via dynamic imports
+
+**Recommended workflow:**
+
+1. **Preview first:** Always run with `--dry-run` to see what will change:
+   ```bash
+   npx i18next-cli instrument --dry-run
+   ```
+
+2. **Interactive mode for initial migration:** Use `--interactive` to approve each candidate:
+   ```bash
+   npx i18next-cli instrument --interactive
+   ```
+
+3. **Review and commit:** Check the changes, then commit to git before proceeding
+
+4. **Run extraction:** After instrumentation, run `extract` to sync with translation files:
+   ```bash
+   npx i18next-cli extract
+   ```
+
+**Limitations:**
+
+The `instrument` command uses heuristic-based detection and has the following limitations:
+
+- **Heuristic-based:** Detection is based on pattern matching and heuristics, not semantic understanding. Expect false positives (marking non-translatable strings for translation) and false negatives (missing translatable strings).
+- **Requires Manual Review:** Every suggested transformation should be carefully reviewed. The command makes a best-effort guess but cannot understand context like a human developer can.
+- **Plurals & Interpolations:** Strings requiring pluralization or variable interpolation need manual cleanup (the command generates basic `t()` calls without plural handling).
+- **Very Dynamic Strings:** Strings built from concatenation, template operations, or computed values may not be detected correctly.
+- **Framework-specific Patterns:** Some framework-specific translation patterns (e.g., decorators, custom hooks, directives) may not be recognized.
+- **Test Files:** Test files are deliberately excluded to avoid instrumenting mock or test data.
+- **Object Keys & Edge Cases:** Complex usage patterns (strings as object keys, switch cases, etc.) may be incorrectly flagged or missed.
+- **Context Loss:** The heuristics can't understand your domain or application context, so legitimate false positives are expected in specialized codebases.
+
+**Expected Workflow:**
+
+The intended usage pattern is:
+1. Run `--dry-run` to preview all suggestions
+2. Use `--interactive` and **carefully review each suggestion** — consider using `edit-key` or `skip` liberally
+3. Commit the instrumented code to version control
+4. Run the full test suite to catch any issues
+5. Manually fix any false positives or false negatives
+6. Run `extract` to finalize translation files
+
 ### `migrate-config`
 Automatically migrates a legacy `i18next-parser.config.js` file to the new `i18next.config.ts` format.
 
@@ -582,7 +739,7 @@ export default defineConfig({
 
 ### Plugin System
 
-Create custom plugins to extend the capabilities of `i18next-cli`. The plugin system provides hooks for both extraction and linting, with a single unified `plugins` array.
+Create custom plugins to extend the capabilities of `i18next-cli`. The plugin system provides hooks for extraction, linting, and instrumentation, with a single unified `plugins` array.
 
 **Available Hooks:**
 
@@ -604,6 +761,16 @@ Create custom plugins to extend the capabilities of `i18next-cli`. The plugin sy
   - Return `null` to skip linting the file entirely.
 - `lintOnResult(filePath, issues)`: Runs after each file is linted. Return a new issues array to filter/augment results, or `undefined` to keep as-is.
 
+**Instrument Plugin Hooks:**
+
+- `instrumentSetup(context)`: Runs once before instrumentation starts. Receives `InstrumentPluginContext` with `config` and `logger`.
+- `instrumentExtensions`: Optional extension hint (for example `['.vue']`). Used as a skip hint/optimization.
+- `instrumentOnLoad(code, filePath)`: Runs before scanning each file for hardcoded strings.
+  - Return `string` to replace source code before scanning.
+  - Return `undefined` to pass through unchanged.
+  - Return `null` to skip instrumenting the file entirely.
+- `instrumentOnResult(filePath, candidates)`: Runs after candidates are detected. Return a new `CandidateString[]` to filter/augment results, or `undefined` to keep as-is.
+
 ### Lint Plugin API
 
 ```typescript
@@ -614,7 +781,8 @@ import type {
   LintIssue,
 } from 'i18next-cli';
 
-// You can type your plugin as Plugin (full surface) or LinterPlugin (lint-focused)
+// You can type your plugin as Plugin (full surface), LinterPlugin (lint-focused),
+// or InstrumenterPlugin (instrument-focused)
 export const vueLintPlugin = (): LinterPlugin => ({
   name: 'vue-lint-plugin',
   lintExtensions: ['.vue'],
@@ -633,7 +801,34 @@ export const vueLintPlugin = (): LinterPlugin => ({
 });
 ```
 
-**Config usage (same plugins list for extract + lint):**
+### Instrument Plugin API
+
+```typescript
+import type {
+  InstrumenterPlugin,
+  InstrumentPluginContext,
+  CandidateString,
+} from 'i18next-cli';
+
+export const vueInstrumentPlugin = (): InstrumenterPlugin => ({
+  name: 'vue-instrument-plugin',
+  instrumentExtensions: ['.vue'],
+  instrumentSetup: async (context: InstrumentPluginContext) => {
+    context.logger.info('vue instrument plugin initialized');
+  },
+  instrumentOnLoad: async (code, filePath) => {
+    if (!filePath.endsWith('.vue')) return undefined;
+    // Extract template block from SFC and return as JSX-like code
+    return code;
+  },
+  instrumentOnResult: async (_filePath, candidates: CandidateString[]) => {
+    // Example: only keep high-confidence candidates
+    return candidates.filter(c => c.confidence >= 0.5);
+  }
+});
+```
+
+**Config usage (same plugins list for extract + lint + instrument):**
 
 ```typescript
 import { defineConfig } from 'i18next-cli';

package/dist/cjs/cli.js

@@ -23,12 +23,15 @@ var linter = require('./linter.js');
 var status = require('./status.js');
 var locize = require('./locize.js');
 var renameKey = require('./rename-key.js');
+var instrumenter = require('./instrumenter/core/instrumenter.js');
+require('./utils/jsx-attributes.js');
+require('magic-string');
 
 const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.46.3'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.0'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program
@@ -204,6 +207,52 @@ program
         }
     }
 });
+program
+    .command('instrument')
+    .description('Scan for hardcoded strings and instrument your code with i18next calls.')
+    .option('--dry-run', 'Preview changes without writing files to disk.')
+    .option('--interactive', 'Prompt for approval of each candidate string.')
+    .option('--namespace <ns>', 'Target a specific namespace for extracted keys.')
+    .option('-q, --quiet', 'Suppress spinner and output')
+    .action(async (options) => {
+    try {
+        const cfgPath = program.opts().config;
+        const config$1 = await config.ensureConfig(cfgPath);
+        const results = await instrumenter.runInstrumenter(config$1, {
+            isDryRun: !!options.dryRun,
+            isInteractive: !!options.interactive,
+            namespace: options.namespace,
+            quiet: !!options.quiet
+        });
+        // Display results
+        if (!options.quiet) {
+            console.log(node_util.styleText('bold', '\nInstrumentation Summary:'));
+            console.log(`  Total candidates: ${results.totalCandidates}`);
+            console.log(`  Approved: ${results.totalTransformed}`);
+            console.log(`  Skipped: ${results.totalSkipped}`);
+            if (results.totalLanguageChanges > 0) {
+                console.log(`  Language-change sites: ${results.totalLanguageChanges}`);
+            }
+            if (options.dryRun) {
+                console.log(node_util.styleText('blue', '\n📋 Dry-run mode enabled. No files were modified.'));
+                console.log('Run again without --dry-run to apply changes.');
+            }
+            if (results.files.length > 0) {
+                console.log(node_util.styleText('green', `\n✅ ${results.files.length} file(s) ready for instrumentation`));
+            }
+            else {
+                console.log(node_util.styleText('yellow', '\n⚠️  No files required instrumentation'));
+            }
+            if (results.totalTransformed > 0 && !options.dryRun) {
+                console.log(node_util.styleText('cyan', '\n💡 Next step: run `i18next-cli extract` to extract the translation keys into your locale files.'));
+            }
+        }
+    }
+    catch (error) {
+        console.error(node_util.styleText('red', 'Error running instrument command:'), error);
+        process.exit(1);
+    }
+});
 program
     .command('locize-sync')
     .description('Synchronize local translations with your Locize project.')

package/dist/cjs/extractor/core/extractor.js

@@ -57,12 +57,17 @@ async function runExtractor(config, options = {}) {
         spinner.text = `Found ${allKeys.size} unique keys. Updating translation files...`;
         const results = await translationManager.getTranslations(allKeys, objectKeys, config, {
             syncPrimaryWithDefaults: options.syncPrimaryWithDefaults,
-            syncAll: options.syncAll
+            syncAll: options.syncAll,
+            logger: options.logger
         });
         let anyFileUpdated = false;
+        let anyNewFile = false;
         for (const result of results) {
             if (result.updated) {
                 anyFileUpdated = true;
+                if (Object.keys(result.existingTranslations || {}).length === 0) {
+                    anyNewFile = true;
+                }
                 if (!options.isDryRun) {
                     // prefer explicit outputFormat; otherwise infer from file extension per-file
                     const effectiveFormat = config.extract.outputFormat ?? fileUtils.inferFormatFromPath(result.path);
@@ -88,8 +93,10 @@ async function runExtractor(config, options = {}) {
             : node_util.styleText('bold', 'Extraction complete!');
         spinner.succeed(completionMessage);
         // Show the funnel message only if files were actually changed.
-        if (anyFileUpdated)
-            await printLocizeFunnel(options.logger);
+        // When new translation files are created (new namespace or first extraction),
+        // always show the funnel regardless of cooldown.
+        if (anyFileUpdated && !options.isDryRun)
+            await printLocizeFunnel(options.logger, anyNewFile);
         return { anyFileUpdated, hasErrors: fileErrors.length > 0 };
     }
     catch (error) {
@@ -250,24 +257,27 @@ async function extract(config, { syncPrimaryWithDefaults = false } = {}) {
  * Prints a promotional message for the locize saveMissing workflow.
  * This message is shown after a successful extraction that resulted in changes.
  */
-async function printLocizeFunnel(logger$1) {
-    if (!(await funnelMsgTracker.shouldShowFunnel('extract')))
+async function printLocizeFunnel(logger$1, force) {
+    if (!force && !(await funnelMsgTracker.shouldShowFunnel('extract')))
         return;
     const internalLogger = logger$1 ?? new logger.ConsoleLogger();
-    if (typeof internalLogger.info === 'function') {
-        internalLogger.info(node_util.styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'));
-        internalLogger.info('   Discover a real-time "push" workflow with `saveMissing` and Locize AI,');
-        internalLogger.info('   where keys are created and translated automatically as you code.');
-        internalLogger.info(`   Learn more: ${node_util.styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`);
-        internalLogger.info(`   Watch the video: ${node_util.styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`);
-    }
-    else {
-        console.log(node_util.styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'));
-        console.log('   Discover a real-time "push" workflow with `saveMissing` and Locize AI,');
-        console.log('   where keys are created and translated automatically as you code.');
-        console.log(`   Learn more: ${node_util.styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`);
-        console.log(`   Watch the video: ${node_util.styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`);
-    }
+    const lines = [
+        node_util.styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'),
+        '   Discover a real-time "push" workflow with `saveMissing` and Locize AI/MT,',
+        '   where keys are created and translated automatically as you code.',
+        `   Learn more: ${node_util.styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`,
+        `   Watch the video: ${node_util.styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`,
+        '',
+        '   You can also sync your extracted translations to Locize:',
+        `     ${node_util.styleText('cyan', 'npx i18next-cli locize-sync')}      – upload/sync translations to Locize`,
+        `     ${node_util.styleText('cyan', 'npx i18next-cli locize-migrate')}   – migrate local translations to Locize`,
+        '   Or import them manually via the Locize UI, API, or locize-cli.',
+    ];
+    const log = typeof internalLogger.info === 'function'
+        ? (msg) => internalLogger.info(msg)
+        : (msg) => console.log(msg);
+    for (const line of lines)
+        log(line);
     return funnelMsgTracker.recordFunnelShown('extract');
 }
 

package/dist/cjs/extractor/core/translation-manager.js

@@ -5,6 +5,7 @@ var glob = require('glob');
 var nestedObject = require('../../utils/nested-object.js');
 var fileUtils = require('../../utils/file-utils.js');
 var defaultValue = require('../../utils/default-value.js');
+var logger = require('../../utils/logger.js');
 
 // used for natural language check
 const chars = [' ', ',', '?', '!', ';'];
@@ -208,7 +209,7 @@ function sortObject(obj, config, customSort) {
  * A helper function to build a new translation object for a single namespace.
  * This centralizes the core logic of merging keys.
  */
-function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, namespace, preservePatterns = [], objectKeys = new Set(), syncPrimaryWithDefaults = false, syncAll = false) {
+function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, namespace, preservePatterns = [], objectKeys = new Set(), syncPrimaryWithDefaults = false, syncAll = false, logger$1 = new logger.ConsoleLogger()) {
     const { keySeparator = '.', sort = true, removeUnusedKeys = true, primaryLanguage, defaultValue: emptyDefaultValue = '', pluralSeparator = '_', contextSeparator = '_', preserveContextVariants = false, } = config.extract;
     const nsSep = typeof config.extract.nsSeparator === 'string' ? config.extract.nsSeparator : ':';
     // Keep the raw configured defaultValue so we can distinguish:
@@ -337,7 +338,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
         return false;
     };
     // Filter nsKeys to only include keys relevant to this language
-    const filteredKeys = nsKeys.filter(({ key, hasCount, isOrdinal }) => {
+    const filteredKeys = nsKeys.filter(({ key, hasCount, isOrdinal, explicitDefault }) => {
         // FIRST: Check if key matches preservePatterns and should be excluded
         if (shouldFilterKey(key)) {
             return false;
@@ -363,14 +364,21 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
                 return true;
             // Otherwise fall through and check the explicit suffix as before.
         }
+        // i18next supports a special _zero form that is NOT part of CLDR plural
+        // rules. When the key was explicitly extracted (e.g. from a t() call with
+        // `defaultValue_zero`), always include it regardless of the target
+        // language's Intl.PluralRules categories.
+        // See: https://www.i18next.com/translation-function/plurals#special-zero
+        const lastPart = keyParts[keyParts.length - 1];
+        if (lastPart === 'zero' && explicitDefault) {
+            return true;
+        }
         if (isOrdinal && keyParts.includes('ordinal')) {
             // For ordinal plurals: key_context_ordinal_category or key_ordinal_category
-            const lastPart = keyParts[keyParts.length - 1];
             return targetLanguagePluralCategories.has(`ordinal_${lastPart}`);
         }
         else if (hasCount) {
             // For cardinal plurals: key_context_category or key_category
-            const lastPart = keyParts[keyParts.length - 1];
             return targetLanguagePluralCategories.has(lastPart);
         }
         return true;
@@ -694,13 +702,13 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
         // that was already written by a different extracted key, e.g.:
         //   t("a.b")   => sets a.b = string
         //   t("a.b.c") => tries to descend into a.b which is already a string
-        // In that situation we skip the conflicting key and emit a console.error so
+        // In that situation we skip the conflicting key and emit a log error so
         // developers see the problem immediately — a skipped key becomes a missing
         // translation at runtime.
         if (separator && typeof separator === 'string') {
             const conflictingPath = findNestingConflict(newTranslations, key, separator);
             if (conflictingPath !== null) {
-                console.error(`[i18next-toolkit] Nesting conflict: key "${key}" conflicts with existing key "${conflictingPath}". ` +
+                logger$1.error(`Nesting conflict: key "${key}" conflicts with existing key "${conflictingPath}". ` +
                     `"${key}" will be skipped — fix the overlapping key paths in your source code to avoid missing translations at runtime.`);
                 continue;
             }
@@ -784,7 +792,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
  * // Results contain update status and new/existing translations for each locale.
  * ```
  */
-async function getTranslations(keys, objectKeys, config, { syncPrimaryWithDefaults = false, syncAll = false } = {}) {
+async function getTranslations(keys, objectKeys, config, { syncPrimaryWithDefaults = false, syncAll = false, logger: logger$1 = new logger.ConsoleLogger() } = {}) {
     config.extract.primaryLanguage ||= config.locales[0] || 'en';
     config.extract.secondaryLanguages ||= config.locales.filter((l) => l !== config?.extract?.primaryLanguage);
     const patternsToPreserve = [...(config.extract.preservePatterns || [])];
@@ -872,12 +880,12 @@ async function getTranslations(keys, objectKeys, config, { syncPrimaryWithDefaul
                 const nsKeys = keysByNS.get(nsKey) || [];
                 if (nsKey === NO_NS_TOKEN) {
                     // keys without namespace -> merged into top-level of the merged file
-                    const built = buildNewTranslationsForNs(nsKeys, existingMergedFile, config, locale, undefined, preservePatterns, objectKeys, syncPrimaryWithDefaults);
+                    const built = buildNewTranslationsForNs(nsKeys, existingMergedFile, config, locale, undefined, preservePatterns, objectKeys, syncPrimaryWithDefaults, undefined, logger$1);
                     Object.assign(newMergedTranslations, built);
                 }
                 else {
                     const existingTranslations = existingMergedFile[nsKey] || {};
-                    newMergedTranslations[nsKey] = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, nsKey, preservePatterns, objectKeys, syncPrimaryWithDefaults);
+                    newMergedTranslations[nsKey] = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, nsKey, preservePatterns, objectKeys, syncPrimaryWithDefaults, undefined, logger$1);
                 }
             }
             // Preserve ignored namespaces as-is from the existing merged file
@@ -915,7 +923,7 @@ async function getTranslations(keys, objectKeys, config, { syncPrimaryWithDefaul
                 const outputPath = fileUtils.getOutputPath(config.extract.output, locale, ns);
                 const fullPath = node_path.resolve(process.cwd(), outputPath);
                 const existingTranslations = await fileUtils.loadTranslationFile(fullPath) || {};
-                const newTranslations = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, ns, preservePatterns, objectKeys, syncPrimaryWithDefaults, syncAll);
+                const newTranslations = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, ns, preservePatterns, objectKeys, syncPrimaryWithDefaults, syncAll, logger$1);
                 const oldContent = JSON.stringify(existingTranslations, null, indentation);
                 const newContent = JSON.stringify(newTranslations, null, indentation);
                 // Push one result per namespace file

package/dist/cjs/extractor/parsers/call-expression-handler.js

@@ -705,8 +705,16 @@ class CallExpressionHandler {
                     categories.forEach(cat => allPluralCategories.add(cat));
                 }
             }
-            const pluralCategories = Array.from(allPluralCategories).sort();
             const pluralSeparator = this.config.extract.pluralSeparator ?? '_';
+            // i18next supports a special _zero form (not part of CLDR plural rules).
+            // When defaultValue_zero is present in the options, include 'zero' in the
+            // categories so that key_zero is generated with the correct default value.
+            // See: https://www.i18next.com/translation-function/plurals#special-zero
+            const zeroDefault = astUtils.getObjectPropValue(options, `defaultValue${pluralSeparator}zero`);
+            if (typeof zeroDefault === 'string' && !allPluralCategories.has('zero')) {
+                allPluralCategories.add('zero');
+            }
+            const pluralCategories = Array.from(allPluralCategories).sort();
             // Get all possible default values once at the start
             const defaultValue = astUtils.getObjectPropValue(options, 'defaultValue');
             const otherDefault = astUtils.getObjectPropValue(options, `defaultValue${pluralSeparator}other`);

package/dist/cjs/extractor/parsers/jsx-handler.js

@@ -366,8 +366,17 @@ class JSXHandler {
                     categories.forEach(cat => allPluralCategories.add(cat));
                 }
             }
-            const pluralCategories = Array.from(allPluralCategories).sort();
             const pluralSeparator = this.config.extract.pluralSeparator ?? '_';
+            // i18next supports a special _zero form (not part of CLDR plural rules).
+            // When defaultValue_zero is present in tOptions, include 'zero' in the
+            // categories so that key_zero is generated with the correct default value.
+            if (optionsNode) {
+                const zeroDefault = astUtils.getObjectPropValue(optionsNode, `defaultValue${pluralSeparator}zero`);
+                if (typeof zeroDefault === 'string' && !allPluralCategories.has('zero')) {
+                    allPluralCategories.add('zero');
+                }
+            }
+            const pluralCategories = Array.from(allPluralCategories).sort();
             // Get plural-specific default values from tOptions if available
             let otherDefault;
             let ordinalOtherDefault;

package/dist/cjs/index.js

@@ -10,6 +10,9 @@ var syncer = require('./syncer.js');
 var status = require('./status.js');
 var typesGenerator = require('./types-generator.js');
 var renameKey = require('./rename-key.js');
+var instrumenter = require('./instrumenter/core/instrumenter.js');
+require('./utils/jsx-attributes.js');
+require('magic-string');
 
 
 
@@ -25,3 +28,5 @@ exports.runSyncer = syncer.runSyncer;
 exports.runStatus = status.runStatus;
 exports.runTypesGenerator = typesGenerator.runTypesGenerator;
 exports.runRenameKey = renameKey.runRenameKey;
+exports.runInstrumenter = instrumenter.runInstrumenter;
+exports.writeExtractedKeys = instrumenter.writeExtractedKeys;

package/dist/cjs/init.js

@@ -32,6 +32,39 @@ async function isEsmProject() {
         return true; // Default to ESM if package.json is not found or readable
     }
 }
+/**
+ * Checks whether i18next-cli is listed as a local dependency of the current project.
+ * When running via `npx` without a local install, `defineConfig` would not be available
+ * at runtime, so the generated config should fall back to a plain object export.
+ *
+ * @returns Promise resolving to true if i18next-cli is in dependencies or devDependencies
+ */
+async function isCliLocallyInstalled() {
+    try {
+        const packageJsonPath = node_path.resolve(process.cwd(), 'package.json');
+        const content = await promises.readFile(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(content);
+        const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+        return !!deps['i18next-cli'];
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks whether the project uses TypeScript by looking for a tsconfig.json.
+ *
+ * @returns Promise resolving to true if tsconfig.json exists in the project root
+ */
+async function isTypeScriptProject() {
+    try {
+        await promises.readFile(node_path.resolve(process.cwd(), 'tsconfig.json'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Interactive setup wizard for creating a new i18next-cli configuration file.
  *
@@ -76,12 +109,17 @@ async function runInit() {
     if (detectedConfig && typeof detectedConfig.extract?.output === 'function') {
         delete detectedConfig.extract.output;
     }
+    // Detect whether the project uses TypeScript to set the preferred default
+    const projectUsesTs = await isTypeScriptProject();
+    const tsChoice = 'TypeScript (i18next.config.ts)';
+    const jsChoice = 'JavaScript (i18next.config.js)';
+    const fileTypeChoices = projectUsesTs ? [tsChoice, jsChoice] : [jsChoice, tsChoice];
     const answers = await inquirer.prompt([
         {
             type: 'select',
             name: 'fileType',
             message: 'What kind of configuration file do you want?',
-            choices: ['TypeScript (i18next.config.ts)', 'JavaScript (i18next.config.js)'],
+            choices: fileTypeChoices,
         },
         {
             type: 'input',
@@ -148,23 +186,41 @@ async function runInit() {
         // Fallback
         return JSON.stringify(value);
     }
+    const isLocallyInstalled = await isCliLocallyInstalled();
     let fileContent = '';
-    if (isTypeScript) {
-        fileContent = `import { defineConfig } from 'i18next-cli';
+    if (isLocallyInstalled) {
+        // i18next-cli is a local dependency — use defineConfig for type-safety
+        if (isTypeScript) {
+            fileContent = `import { defineConfig } from 'i18next-cli'
 
-export default defineConfig(${toJs(configObject)});`;
-    }
-    else if (isEsm) {
-        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');
+export default defineConfig(${toJs(configObject)})`;
+        }
+        else { // CJS
+            fileContent = `const { defineConfig } = require('i18next-cli')
 
 /** @type {import('i18next-cli').I18nextToolkitConfig} */
-module.exports = defineConfig(${toJs(configObject)});`;
+module.exports = defineConfig(${toJs(configObject)})`;
+        }
+    }
+    else {
+        // i18next-cli is not locally installed (e.g. npx) — plain config object
+        if (isTypeScript) {
+            fileContent = `export default ${toJs(configObject)}`;
+        }
+        else if (isEsm) {
+            fileContent = `/** @type {import('i18next-cli').I18nextToolkitConfig} */
+export default ${toJs(configObject)}`;
+        }
+        else { // CJS
+            fileContent = `/** @type {import('i18next-cli').I18nextToolkitConfig} */
+module.exports = ${toJs(configObject)}`;
+        }
     }
     const outputPath = node_path.resolve(process.cwd(), fileName);
     await promises.writeFile(outputPath, fileContent.trim());