i18next-cli 1.61.0 → 1.62.0

package/README.md

@@ -58,6 +58,8 @@ npm install --save-dev i18next-cli
 
 ## Quick Start
 
+> **Zero-to-localized in one command:** starting from an app with hardcoded strings (e.g. generated with v0, Lovable, Bolt or Cursor)? Run `npx i18next-cli localize` — it detects your setup, wraps hardcoded strings in `t()` calls, extracts keys, connects to [Locize](https://www.locize.com) and AI-translates your app. See [the `localize` command](#localize). The steps below are the manual path.
+
 ### 1. Initialize Configuration
 
 Create a configuration interactively:
@@ -468,6 +470,101 @@ Both the `lint` and `instrument` commands honor an ignore comment so you can ski
 const msg = t('Hello {{name}}!', { wrong: 'world' })
 ```
 
+### `localize`
+
+One command from hardcoded strings to a fully localized app: detect, instrument, extract, connect to [Locize](https://www.locize.com), AI-auto-translate, deliver. Built for taking a mono-lingual app (often AI-generated via v0/Lovable/Bolt/Cursor) to fully localized in one sitting.
+
+```bash
+npx i18next-cli localize
+```
+
+The command walks through six steps:
+
+1. **Detect** — framework (React/Next.js natively; see below for other stacks), TypeScript, existing i18next setup.
+2. **Configuration** — uses your `i18next.config.ts`, or starts the [`init`](#init) wizard if none exists.
+3. **Instrument** — wraps hardcoded strings in `t()` calls / `<Trans>` components (interactive by default — [instrument](#instrument) is an assistant, review each change). Skipped automatically if your code can't be instrumented; a dirty git tree prompts for confirmation first.
+4. **Extract** — extracts all translation keys into your locale files.
+5. **Connect Locize** — uses `locize.projectId`/`locize.apiKey` from your config or the `LOCIZE_PROJECTID`/`LOCIZE_API_KEY` environment variables; otherwise it opens the signup page and asks you to paste them (the one manual step). Any write-capable API key works: your target languages are created automatically on the first sync (locize-cli ≥ 12.3), and auto-translate + Quality Estimation are on by default for new Locize projects.
+6. **Translate & deliver** — syncs your keys with `--auto-translate`, waits for the AI translations to arrive, downloads them, and prints the [i18next-locize-backend](https://github.com/locize/i18next-locize-backend) CDN wiring snippet (so translation fixes go live without redeploying your app).
+
+**Options:**
+- `--dry-run`: Preview every step; nothing is written or pushed
+- `-y, --yes`: Accept defaults; auto-approve instrumentation candidates (no per-string prompts)
+- `--ci`: Non-interactive; never opens a browser or prompts. Instrumentation is **skipped** in CI (it rewrites source files and needs human review) unless combined with `--yes`
+- `--skip-instrument`: Skip the code-instrumentation step (your code already calls `t()`)
+- `--skip-translate`: Sync to Locize but don't request AI auto-translation
+- `--skip-locize`: Stop after extraction (local files only)
+- `--namespace <ns>`: Target namespace for instrumented keys
+- `--update-values`: Also update existing translation values on Locize
+- `--cdn-type <standard|pro>`: Locize CDN endpoint type
+- `--print-agent-prompt`: Print a copy-paste prompt for AI coding agents, then exit (see below)
+
+**Behavior matrix:**
+
+| Step | interactive (default) | `--yes` | `--ci` | `--dry-run` |
+|---|---|---|---|---|
+| Instrument | per-string prompts | auto-approve | skipped (force with `--yes`) | candidate preview |
+| Connect Locize | browser + paste credentials | same | env vars required, else exit 1 | report only |
+| Sync + translate | runs | runs | runs | `--dry` forwarded |
+| Poll + download | watches translations arrive | same | single download, no wait | skipped |
+
+**Safe to re-run:** the command is idempotent. Already-wrapped strings are not re-instrumented, extraction is deterministic, and syncing never overwrites translations edited remotely (no `--update-values` unless you pass it; locize-cli's `--reference-language-only` default keeps target languages safe).
+
+> **Next.js App Router:** instrument injects `useTranslation()`, which is client-only. Review the diff for server components — add `'use client'` or switch those to a server-side `t()` pattern.
+
+**Non-React stacks (Vue, Svelte, …):** the instrument step transforms React/JSX out of the box. For other stacks, add a plugin that covers your file type (community: [i18next-cli-vue](https://github.com/PBK-B/i18next-cli-vue), [i18next-cli-plugin-svelte](https://github.com/dreamscached/i18next-cli-plugin-svelte) — or write your own via the [Plugin System](#plugin-system) `instrumentOnLoad`/`onLoad` hooks). With a matching plugin configured, `localize` runs the full flow; without one, the instrument step is skipped with guidance and the remaining steps (extract → Locize → auto-translate) still run.
+
+**Agent prompt:** the same flow is available as a copy-paste prompt for AI coding agents (Claude Code, Cursor, …):
+
+```bash
+npx i18next-cli localize --print-agent-prompt
+```
+
+This prints step-by-step instructions an agent can follow using the individual CLI commands — version-matched to your installed CLI, so it never drifts from what the supercommand does. Prefer the command output over the copy below, which is a snapshot for reference:
+
+<details>
+<summary>Agent prompt (snapshot)</summary>
+
+```text
+You are localizing this app with i18next + Locize. Execute these steps in order,
+verifying each before continuing. Use `npx i18next-cli` for all commands.
+
+1. Detect: confirm this is a React/Next.js project (check package.json).
+   - If Vue/Svelte: install a stack plugin (`i18next-cli-vue` /
+     `i18next-cli-plugin-svelte`) and add it to the `plugins` array of
+     i18next.config.ts, or write one via the plugin hooks
+     (instrumentOnLoad/onLoad) instead of wrapping strings manually.
+   - If the app uses inlang Paraglide (`@inlang/paraglide-js`), STOP —
+     instrumenting i18next calls would conflict; ask the user how to proceed.
+2. Config: if no i18next.config.{ts,js} exists, run `npx i18next-cli init`
+   and answer the prompts (pick Locize as backend if the user wants managed
+   translations and AI auto-translate).
+3. Instrument: run `npx i18next-cli instrument --dry-run` and review the
+   planned changes; then `npx i18next-cli instrument` to apply. Inspect the
+   git diff carefully: fix any t() wrapping inside Next.js *server components*
+   (add 'use client' or refactor to a server-side t() pattern). Commit.
+4. Extract: run `npx i18next-cli extract`. Verify the locale JSON files were
+   written (check the extract.output path in the config).
+5. Locize: ask the user for LOCIZE_PROJECTID and LOCIZE_API_KEY (they create
+   the project at https://www.locize.app/register?from=i18next_cli__agent-prompt
+   — any write-capable API key works; the target languages from
+   i18next.config.ts are created automatically on the first sync.
+   Auto-translation and quality estimation are enabled by default for new
+   projects; translations run once the project is subscribed or an AI/MT
+   provider is configured). Export both as environment variables.
+6. Translate & deliver:
+   `npx i18next-cli locize-sync --auto-translate true`
+   then `npx i18next-cli locize-download` to pull the AI translations, and
+   `npx i18next-cli status` — confirm all languages are (near) 100%.
+   AI translation is asynchronous; if targets are still empty, wait a minute
+   and re-run locize-download.
+7. Optionally switch runtime loading to i18next-locize-backend (CDN delivery,
+   so translation fixes go live without redeploying). NEVER put the API key
+   in client-side code — the CDN only needs the project ID.
+```
+
+</details>
+
 ### `migrate-config`
 Automatically migrates a legacy `i18next-parser.config.js` file to the new `i18next.config.ts` format.
 
@@ -543,9 +640,29 @@ npx i18next-cli locize-sync [options]
 
 **Options:**
 - `--update-values`: Update values of existing translations on locize
-- `--src-lng-only`: Check for changes in source language only
+- `--src-lng-only <true|false>`: Check for changes in source language only (default: `true`). Pass `--src-lng-only false` to sync all languages
 - `--compare-mtime`: Compare modification times when syncing
 - `--dry-run`: Run the command without making any changes
+- `--auto-translate <true|false>`: Trigger AI/MT auto-translation of newly synced keys. Requires auto-translation in your Locize project (enabled by default for new projects; runs once the project is subscribed or an AI/MT provider is configured)
+- `--auto-translate-review <true|false>`: Route auto-translated segments through the review workflow for languages that have review enabled
+- `--auto-translate-languages <lng1,lng2>`: Restrict auto-translation to these target languages (defaults to all)
+
+The same options can be set persistently in the `locize` block of your config:
+
+```typescript
+export default defineConfig({
+  // ...
+  locize: {
+    projectId: '...',
+    apiKey: process.env.LOCIZE_API_KEY,
+    autoTranslate: true,
+    autoTranslateReview: false,
+    autoTranslateLanguages: ['de', 'fr'],
+  },
+});
+```
+
+> **Note:** auto-translation only fires when the **reference language** is updated, and the translation itself happens asynchronously on the Locize side — run `locize-download` (or let [`localize`](#localize) wait for you) to pull the results.
 
 **Interactive Setup:** If your locize credentials are missing or invalid, the toolkit will guide you through an interactive setup process to configure your Project ID, API Key, and version.
 
@@ -1599,6 +1716,7 @@ class I18nextExtractionPlugin {
 - `runSyncer(config)` - Sync translation files
 - `runStatus(config, options?)` - Get translation status
 - `runTypesGenerator(config)` - Generate types
+- `runLocalize(options?, configPath?)` - The full [`localize`](#localize) flow (detect → instrument → extract → Locize sync with auto-translate → download)
 
 ### Advanced Usage
 

package/dist/cjs/cli.js

@@ -27,12 +27,17 @@ var renameKey = require('./rename-key.js');
 var instrumenter = require('./instrumenter/core/instrumenter.js');
 require('./utils/jsx-attributes.js');
 require('magic-string');
+var localize = require('./localize/localize.js');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var chokidar__default = /*#__PURE__*/_interopDefault(chokidar);
 
 const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.61.0'); // This string is replaced with the actual version at build time by rollup
+    .version('1.62.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
@@ -93,7 +98,7 @@ program
             const ignoreGlobs = [...configuredIgnore, ...derivedIgnore].filter(Boolean);
             // filter expanded files by ignore globs
             const watchFiles = expanded.filter(f => !ignoreGlobs.some(g => minimatch.minimatch(f, g, { dot: true })));
-            const watcher = chokidar.watch(watchFiles, {
+            const watcher = chokidar__default.default.watch(watchFiles, {
                 ignored: /node_modules/,
                 persistent: true,
             });
@@ -163,7 +168,7 @@ program
         const watchTypes = expandedTypes.filter(f => !ignoredTypes.some(g => minimatch.minimatch(f, g, { dot: true })));
         // awaitWriteFinish avoids triggering mid-write when another process (e.g. `extract -w`)
         // is rewriting the same translation files. See i18next/i18next-cli#257.
-        const watcher = chokidar.watch(watchTypes, {
+        const watcher = chokidar__default.default.watch(watchTypes, {
             persistent: true,
             awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
         });
@@ -229,7 +234,7 @@ program
             const derivedIgnore2 = deriveOutputIgnore(config$1.extract.output);
             const ignoredLint = [...configuredIgnore2, ...derivedIgnore2].filter(Boolean);
             const watchLint = expandedLint.filter(f => !ignoredLint.some(g => minimatch.minimatch(f, g, { dot: true })));
-            const watcher = chokidar.watch(watchLint, {
+            const watcher = chokidar__default.default.watch(watchLint, {
                 ignored: /node_modules/,
                 persistent: true,
             });
@@ -286,14 +291,40 @@ program
         process.exit(1);
     }
 });
+program
+    .command('localize')
+    .description('One command from hardcoded strings to a fully localized app: detect, instrument, extract, connect to Locize, auto-translate, deliver.')
+    .option('--dry-run', 'Preview every step; nothing is written or pushed.')
+    .option('-y, --yes', 'Accept defaults; auto-approve instrumentation candidates (no per-string prompts).')
+    .option('--ci', 'Non-interactive: never open a browser or prompt; instrument is skipped (combine with --yes to force non-interactive instrumentation).')
+    .option('--skip-instrument', 'Skip the code-instrumentation step (use when your code already calls t()).')
+    .option('--skip-translate', 'Sync to Locize but do not request AI auto-translation.')
+    .option('--skip-locize', 'Stop after extraction (local files only; steps 5-6 skipped).')
+    .option('--namespace <ns>', 'Target namespace for instrumented keys (forwarded to instrument).')
+    .option('--update-values', 'Also update existing translation values on Locize (forwarded to sync).')
+    .option('--cdn-type <standard|pro>', 'Specify the cdn endpoint that should be used (depends on which cdn type you\'ve in your Locize project)')
+    .option('--print-agent-prompt', 'Print a copy-paste prompt for AI coding agents (Claude Code, Cursor) that performs the same steps, then exit.')
+    .action(async (options) => {
+    try {
+        const cfgPath = program.opts().config;
+        await localize.runLocalize(options, cfgPath);
+    }
+    catch (error) {
+        console.error(node_util.styleText('red', 'Error running localize command:'), error);
+        process.exit(1);
+    }
+});
 program
     .command('locize-sync')
     .description('Synchronize local translations with your Locize project.')
     .option('--update-values', 'Update values of existing translations on Locize.')
-    .option('--src-lng-only', 'Check for changes in source language only.')
+    .option('--src-lng-only <true|false>', 'Check for changes in source language only. (default: true)')
     .option('--compare-mtime', 'Compare modification times when syncing.')
     .option('--dry-run', 'Run the command without making any changes.')
     .option('--cdn-type <standard|pro>', 'Specify the cdn endpoint that should be used (depends on which cdn type you\'ve in your locize project)')
+    .option('--auto-translate <true|false>', 'Trigger AI/MT auto-translation of newly synced keys (requires auto-translation enabled in your Locize project; on by default for new projects).')
+    .option('--auto-translate-review <true|false>', 'Route auto-translated segments through the review workflow for languages that have review enabled.')
+    .option('--auto-translate-languages <lng1,lng2>', 'Restrict auto-translation to these target languages (comma separated; defaults to all languages).')
     .action(async (options) => {
     const cfgPath = program.opts().config;
     const config$1 = await config.ensureConfig(cfgPath);

package/dist/cjs/config.js

@@ -10,6 +10,10 @@ var node_util = require('node:util');
 var init = require('./init.js');
 var logger = require('./utils/logger.js');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var inquirer__default = /*#__PURE__*/_interopDefault(inquirer);
+
 /**
  * List of supported configuration file names in order of precedence
  */
@@ -128,7 +132,7 @@ async function ensureConfig(configPath, logger$1 = new logger.ConsoleLogger()) {
         return config;
     }
     // No config found, so we prompt the user.
-    const { shouldInit } = await inquirer.prompt([{
+    const { shouldInit } = await inquirer__default.default.prompt([{
             type: 'confirm',
             name: 'shouldInit',
             message: node_util.styleText('yellow', 'Configuration file not found. Would you like to create one now?'),

package/dist/cjs/index.js

@@ -13,6 +13,10 @@ var renameKey = require('./rename-key.js');
 var instrumenter = require('./instrumenter/core/instrumenter.js');
 require('./utils/jsx-attributes.js');
 require('magic-string');
+var localize = require('./localize/localize.js');
+require('node:fs/promises');
+require('node:path');
+var agentPrompt = require('./localize/agent-prompt.js');
 
 
 
@@ -30,3 +34,5 @@ exports.runTypesGenerator = typesGenerator.runTypesGenerator;
 exports.runRenameKey = renameKey.runRenameKey;
 exports.runInstrumenter = instrumenter.runInstrumenter;
 exports.writeExtractedKeys = instrumenter.writeExtractedKeys;
+exports.runLocalize = localize.runLocalize;
+exports.AGENT_PROMPT = agentPrompt.AGENT_PROMPT;

package/dist/cjs/init.js

@@ -3,58 +3,14 @@
 var inquirer = require('inquirer');
 var promises = require('node:fs/promises');
 var node_path = require('node:path');
-var execa = require('execa');
 var heuristicConfig = require('./heuristic-config.js');
+var locizeOnboarding = require('./utils/locize-onboarding.js');
 
-const LOCIZE_SIGNUP_URL = 'https://www.locize.app/register?from=i18next-cli+init+wizard';
-/** Rough 8-4-4-4-12 hex UUID shape — not strict (locize project IDs may evolve). */
-const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
- * Opens the given URL in the user's default browser using the platform-native command.
- * Returns true on success, false if there's nowhere to open one (CI, headless Linux)
- * or if spawning the command failed.
- */
-async function openBrowser(url, opts = {}) {
-    // Short-circuit: no point spawning a browser-opener in CI or headless Linux.
-    if (opts.ci || process.env.CI === 'true')
-        return false;
-    const isWSL = !!process.env.WSL_DISTRO_NAME;
-    if (process.platform === 'linux' && !isWSL &&
-        !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
-        return false;
-    }
-    try {
-        if (process.platform === 'darwin') {
-            await execa.execa('open', [url], { stdio: 'ignore' });
-        }
-        else if (process.platform === 'win32') {
-            // `start` is a cmd.exe builtin; the empty "" is the window-title slot
-            await execa.execa('cmd', ['/c', 'start', '""', url], { stdio: 'ignore' });
-        }
-        else if (isWSL) {
-            // WSL: try the wslu / wsl-open shims that bridge to the Windows side
-            // before falling back to xdg-open (which usually isn't installed there).
-            try {
-                await execa.execa('wslview', [url], { stdio: 'ignore' });
-            }
-            catch {
-                try {
-                    await execa.execa('wsl-open', [url], { stdio: 'ignore' });
-                }
-                catch {
-                    await execa.execa('xdg-open', [url], { stdio: 'ignore' });
-                }
-            }
-        }
-        else {
-            await execa.execa('xdg-open', [url], { stdio: 'ignore' });
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var inquirer__default = /*#__PURE__*/_interopDefault(inquirer);
+
+const LOCIZE_SIGNUP_URL = 'https://www.locize.app/register?from=i18next_cli__init-wizard';
 /**
  * Determines if the current project is configured as an ESM project.
  * Checks the package.json file for `"type": "module"`.
@@ -164,7 +120,7 @@ async function runInit(options = {}) {
     const tsChoice = 'TypeScript (i18next.config.ts)';
     const jsChoice = 'JavaScript (i18next.config.js)';
     const fileTypeChoices = projectUsesTs ? [tsChoice, jsChoice] : [jsChoice, tsChoice];
-    const answers = await inquirer.prompt([
+    const answers = await inquirer__default.default.prompt([
         {
             type: 'select',
             name: 'fileType',
@@ -208,33 +164,11 @@ async function runInit(options = {}) {
     let locizeConfig;
     if (answers.backend === 'locize') {
         console.log('\nOpening the Locize signup page in your browser. After you create your account and project, come back here and paste your Project ID and API key.');
-        const opened = await openBrowser(LOCIZE_SIGNUP_URL, { ci: options.ci });
+        const opened = await locizeOnboarding.openBrowser(LOCIZE_SIGNUP_URL, { ci: options.ci });
         if (!opened) {
             console.log(`\n👉 Open this URL manually: ${LOCIZE_SIGNUP_URL}\n`);
         }
-        const credentials = await inquirer.prompt([
-            {
-                type: 'input',
-                name: 'projectId',
-                message: 'Locize Project ID (e.g. 4eeb5ce0-a7a7-453f-8eb3-078f6eeb56fe):',
-                validate: (input) => input.trim().length > 0 || 'Project ID cannot be empty.',
-                filter: (input) => input.trim(),
-            },
-            {
-                type: 'password',
-                name: 'apiKey',
-                message: 'Locize API key (needed for saveMissing / auto-publish / sync during development; leave empty to skip and add later via env var):',
-                filter: (input) => input.trim(),
-            },
-        ]);
-        if (!UUID_SHAPE.test(credentials.projectId)) {
-            console.log("⚠️  The Project ID doesn't look like a UUID (8-4-4-4-12 hex). It will still be written — double-check it in your Locize project settings.");
-        }
-        // API keys come in multiple shapes (UUID, `lz_pat_…`, `lz_api_…`, etc.) —
-        // treat them as opaque; no client-side format check.
-        locizeConfig = { projectId: credentials.projectId };
-        if (credentials.apiKey)
-            locizeConfig.apiKey = credentials.apiKey;
+        locizeConfig = await locizeOnboarding.promptLocizeCredentials();
     }
     const isTypeScript = answers.fileType.includes('TypeScript');
     const isEsm = await isEsmProject();

package/dist/cjs/instrumenter/core/instrumenter.js

@@ -15,6 +15,10 @@ var jsxAttributes = require('../../utils/jsx-attributes.js');
 var astUtils = require('../../extractor/parsers/ast-utils.js');
 var fileUtils = require('../../utils/file-utils.js');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var inquirer__default = /*#__PURE__*/_interopDefault(inquirer);
+
 /**
  * Main orchestrator for the instrument command.
  * Scans source files for hardcoded strings and instruments them with i18next calls.
@@ -50,7 +54,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
         let targetNamespace = options.namespace;
         if (!targetNamespace && options.isInteractive) {
             const defaultNS = config.extract.defaultNS ?? 'translation';
-            const { ns } = await inquirer.prompt([
+            const { ns } = await inquirer__default.default.prompt([
                 {
                     type: 'input',
                     name: 'ns',
@@ -83,7 +87,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
                 if (options.isInteractive) {
                     // Ask user about each candidate
                     for (const candidate of candidates) {
-                        const { action } = await inquirer.prompt([
+                        const { action } = await inquirer__default.default.prompt([
                             {
                                 type: 'list',
                                 name: 'action',
@@ -104,7 +108,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
                                 candidate.skipReason = 'User skipped';
                                 break;
                             case 'edit-key': {
-                                const { key } = await inquirer.prompt([
+                                const { key } = await inquirer__default.default.prompt([
                                     {
                                         type: 'input',
                                         name: 'key',
@@ -116,7 +120,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
                                 break;
                             }
                             case 'edit-value': {
-                                const { value } = await inquirer.prompt([
+                                const { value } = await inquirer__default.default.prompt([
                                     {
                                         type: 'input',
                                         name: 'value',
@@ -1462,6 +1466,24 @@ const I18N_INIT_FILE_NAMES = [
     'i18n/index.ts', 'i18n/index.js', 'i18n/index.mjs',
     'i18next/index.ts', 'i18next/index.js'
 ];
+/**
+ * Searches the common locations (`src/` and the project root) for an existing
+ * i18n initialization file.
+ *
+ * @returns The path of the first init file found (relative to cwd), or null.
+ */
+async function findExistingI18nInitFile() {
+    const cwd = process.cwd();
+    const searchDirs = ['src', '.'];
+    for (const dir of searchDirs) {
+        for (const name of I18N_INIT_FILE_NAMES) {
+            if (await fileExists(node_path.join(cwd, dir, name))) {
+                return node_path.join(dir, name);
+            }
+        }
+    }
+    return null;
+}
 /**
  * Computes a POSIX-style relative path from the init-file directory to the
  * output template path (which still contains {{language}} / {{namespace}} placeholders).
@@ -1487,13 +1509,8 @@ function buildDynamicImportPath(outputTemplate, initDir) {
 async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger, usesI18nextT) {
     const cwd = process.cwd();
     // Check for existing init files in common locations
-    const searchDirs = ['src', '.'];
-    for (const dir of searchDirs) {
-        for (const name of I18N_INIT_FILE_NAMES) {
-            if (await fileExists(node_path.join(cwd, dir, name))) {
-                return null; // Init file already exists
-            }
-        }
+    if (await findExistingI18nInitFile()) {
+        return null; // Init file already exists
     }
     // Check if i18next.init() is called anywhere in the source
     try {
@@ -1941,5 +1958,9 @@ async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugin
     return candidates;
 }
 
+exports.detectProjectEnvironment = detectProjectEnvironment;
+exports.findExistingI18nInitFile = findExistingI18nInitFile;
+exports.isProjectUsingReact = isProjectUsingReact;
+exports.isProjectUsingTypeScript = isProjectUsingTypeScript;
 exports.runInstrumenter = runInstrumenter;
 exports.writeExtractedKeys = writeExtractedKeys;

package/dist/cjs/instrumenter/core/transformer.js

@@ -3,6 +3,10 @@
 var MagicString = require('magic-string');
 var keyGenerator = require('./key-generator.js');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var MagicString__default = /*#__PURE__*/_interopDefault(MagicString);
+
 /**
  * Transforms a source file, replacing candidate strings with instrumented code.
  * Also injects useTranslation() hooks into React function components that
@@ -15,7 +19,7 @@ var keyGenerator = require('./key-generator.js');
  * @returns TransformResult with modified content and diff
  */
 function transformFile(content, file, candidates, options) {
-    const s = new MagicString(content);
+    const s = new MagicString__default.default(content);
     const errors = [];
     const warnings = [];
     let transformCount = 0;

package/dist/cjs/localize/agent-prompt.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * Copy-paste prompt for AI coding agents (Claude Code, Cursor, …) that walks
+ * an agent through the same steps the `localize` command orchestrates.
+ *
+ * This constant is the single source of truth — it is printed by
+ * `i18next-cli localize --print-agent-prompt` and mirrored in the README.
+ * A test guards that it mentions every orchestrated command, so flow changes
+ * that forget this prompt fail CI.
+ */
+const AGENT_PROMPT = `You are localizing this app with i18next + Locize. Execute these steps in order,
+verifying each before continuing. Use \`npx i18next-cli\` for all commands.
+
+1. Detect: confirm this is a React/Next.js project (check package.json).
+   - If Vue/Svelte: install a stack plugin (\`i18next-cli-vue\` /
+     \`i18next-cli-plugin-svelte\`) and add it to the \`plugins\` array of
+     i18next.config.ts, or write one via the plugin hooks
+     (instrumentOnLoad/onLoad) instead of wrapping strings manually.
+   - If the app uses inlang Paraglide (\`@inlang/paraglide-js\`), STOP —
+     instrumenting i18next calls would conflict; ask the user how to proceed.
+2. Config: if no i18next.config.{ts,js} exists, run \`npx i18next-cli init\`
+   and answer the prompts (pick Locize as backend if the user wants managed
+   translations and AI auto-translate).
+3. Instrument: run \`npx i18next-cli instrument --dry-run\` and review the
+   planned changes; then \`npx i18next-cli instrument\` to apply. Inspect the
+   git diff carefully: fix any t() wrapping inside Next.js *server components*
+   (add 'use client' or refactor to a server-side t() pattern). Commit.
+4. Extract: run \`npx i18next-cli extract\`. Verify the locale JSON files were
+   written (check the extract.output path in the config).
+5. Locize: ask the user for LOCIZE_PROJECTID and LOCIZE_API_KEY (they create
+   the project at https://www.locize.app/register?from=i18next_cli__agent-prompt
+   — any write-capable API key works; the target languages from
+   i18next.config.ts are created automatically on the first sync.
+   Auto-translation and quality estimation are enabled by default for new
+   projects; translations run once the project is subscribed or an AI/MT
+   provider is configured). Export both as environment variables.
+6. Translate & deliver:
+   \`npx i18next-cli locize-sync --auto-translate true\`
+   then \`npx i18next-cli locize-download\` to pull the AI translations, and
+   \`npx i18next-cli status\` — confirm all languages are (near) 100%.
+   AI translation is asynchronous; if targets are still empty, wait a minute
+   and re-run locize-download.
+7. Optionally switch runtime loading to i18next-locize-backend (CDN delivery,
+   so translation fixes go live without redeploying). NEVER put the API key
+   in client-side code — the CDN only needs the project ID.
+`;
+
+exports.AGENT_PROMPT = AGENT_PROMPT;

package/dist/cjs/localize/detect.js

@@ -0,0 +1,88 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+
+async function pathExists(path) {
+    try {
+        await promises.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageDeps() {
+    try {
+        const content = await promises.readFile(node_path.join(process.cwd(), 'package.json'), 'utf-8');
+        const packageJson = JSON.parse(content);
+        return { ...packageJson.dependencies, ...packageJson.devDependencies };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Detects the project stack relevant to the `localize` orchestrator:
+ * frontend framework, i18next presence, an existing i18n init file,
+ * Next.js App Router usage and inlang Paraglide usage.
+ *
+ * All checks are `process.cwd()`-relative (run from the package directory
+ * in monorepos).
+ *
+ * @param findInitFile - locator for an existing i18n init file
+ *                       (injected to reuse the instrumenter's implementation)
+ */
+async function detectStack(findInitFile) {
+    const deps = await readPackageDeps();
+    const has = (name) => !!deps[name];
+    let framework = 'unknown';
+    if (has('next'))
+        framework = 'next';
+    else if (has('react') || has('react-i18next'))
+        framework = 'react';
+    else if (has('vue') || has('nuxt'))
+        framework = 'vue';
+    else if (has('svelte') || has('@sveltejs/kit'))
+        framework = 'svelte';
+    else if (has('@angular/core'))
+        framework = 'angular';
+    const cwd = process.cwd();
+    const hasAppRouter = framework === 'next' &&
+        (await pathExists(node_path.join(cwd, 'app')) || await pathExists(node_path.join(cwd, 'src', 'app')));
+    const hasParaglide = has('@inlang/paraglide-js') || await pathExists(node_path.join(cwd, 'project.inlang'));
+    return {
+        framework,
+        hasI18next: has('i18next') || has('react-i18next'),
+        hasTypeScript: await pathExists(node_path.join(cwd, 'tsconfig.json')),
+        initFile: await findInitFile(),
+        hasAppRouter,
+        hasParaglide,
+    };
+}
+/** File extensions associated with frameworks the instrumenter cannot transform natively. */
+const STACK_EXTENSIONS = {
+    vue: ['.vue', 'vue'],
+    svelte: ['.svelte', 'svelte'],
+};
+/**
+ * Checks whether a configured plugin covers the detected stack's file
+ * extension via `instrumentExtensions` or `lintExtensions` — in which case
+ * the instrument/extract runners can process the stack's files through the
+ * plugin hooks and `localize` runs the full flow.
+ */
+function hasStackPlugin(config, framework) {
+    const extensions = STACK_EXTENSIONS[framework];
+    if (!extensions || !config.plugins?.length)
+        return false;
+    return config.plugins.some((plugin) => {
+        const declared = [
+            ...(plugin.instrumentExtensions || []),
+            ...(plugin.lintExtensions || []),
+        ];
+        return declared.some(ext => extensions.includes(ext));
+    });
+}
+
+exports.detectStack = detectStack;
+exports.hasStackPlugin = hasStackPlugin;