i18next-cli 1.61.1 → 1.63.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:
@@ -116,6 +118,13 @@ npx i18next-cli init
   also auto-detects `CI=true` and falls back to printing the URL on headless
   Linux (no `DISPLAY`/`WAYLAND_DISPLAY`), so this flag is rarely needed
   explicitly.
+- `--inlang`: Also scaffold an [inlang](https://inlang.com) project
+  (`project.inlang/settings.json`) so inlang tooling — the
+  [Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) VS Code
+  extension, the [Fink](https://fink.inlang.com) web editor for translators,
+  and the [Paraglide](https://inlang.com/m/gerre34r/library-inlang-paraglideJs)
+  compiler — works directly on your translation files. Skips the
+  corresponding wizard question.
 
 The wizard asks for the config file type, locales, source-file glob, output
 path, and finally **"Translation backend?"** with three options:
@@ -129,6 +138,28 @@ path, and finally **"Translation backend?"** with three options:
   mode); add it later via a `LOCIZE_API_KEY` environment variable.
 - **Other / skip** — same as "Local files only" for the wizard's purposes.
 
+The wizard then offers to **set up inlang tooling** (default: no — or pass
+`--inlang` to skip the question). If accepted, it scaffolds a
+`project.inlang/settings.json` that points the
+[inlang i18next plugin](https://inlang.com/m/3i8bor92/plugin-inlang-i18next)
+at your existing translation files: `baseLocale`/`locales` come from your
+config, and `pathPattern` is derived from `extract.output` (the namespaced
+object form when your layout uses `{{namespace}}`, with namespaces discovered
+from the primary language's files; a plain pattern otherwise). It also adds
+the Sherlock extension to `.vscode/extensions.json` recommendations (merging
+comment-aware, never clobbering existing entries). Your i18next JSON files
+remain the single source of truth — inlang tools read and write them in
+place, so there is no second catalog to drift. An existing
+`project.inlang/settings.json` is never overwritten; re-running `init` is
+safe. Requires JSON resource files. The plugin is pinned to an exact verified
+version (`@inlang/plugin-i18next@6.2.0`) — bump the `modules` URL in
+`settings.json` to pick up newer plugin releases. Only `settings.json` is
+scaffolded by design: `project.inlang/` is the
+[unpacked (git-friendly)](https://inlang.com/docs/unpacked-project) project
+form, and inlang tools generate and manage its remaining files (`.gitignore`,
+`README.md`, `cache/`) on first use — so expect a few new files there after
+opening the project with Sherlock or Paraglide.
+
 ### `extract`
 Parses source files, extracts keys, and updates your JSON translation files.
 
@@ -468,6 +499,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.
 
@@ -546,6 +672,26 @@ npx i18next-cli locize-sync [options]
 - `--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 +1745,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.1'); // This string is replaced with the actual version at build time by rollup
+    .version('1.63.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 },
         });
@@ -192,7 +197,8 @@ program
     .command('init')
     .description('Create a new i18next.config.ts/js file with an interactive setup wizard.')
     .option('--ci', 'Skip the browser launch when a backend (e.g. Locize) is selected. The signup URL is printed instead.')
-    .action((options) => init.runInit({ ci: !!options.ci }));
+    .option('--inlang', 'Also scaffold an inlang project (project.inlang/settings.json) so inlang tooling (Sherlock, Fink, Paraglide) works on the translation files. Skips the corresponding wizard question.')
+    .action((options) => init.runInit({ ci: !!options.ci, inlang: !!options.inlang }));
 program
     .command('lint')
     .description('Find potential issues like hardcoded strings in your codebase.')
@@ -229,7 +235,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,6 +292,29 @@ 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.')
@@ -294,6 +323,9 @@ program
     .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,15 @@
 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');
+var inlangScaffold = require('./utils/inlang-scaffold.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 +121,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',
@@ -204,37 +161,23 @@ async function runInit(options = {}) {
             ],
             default: 'local',
         },
+        {
+            type: 'confirm',
+            name: 'inlang',
+            message: 'Also set up inlang tooling (Sherlock VS Code extension, Fink editor, Paraglide) on these translation files?',
+            default: false,
+            // Skip the question when already requested via the --inlang flag.
+            when: () => !options.inlang,
+        },
     ]);
     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();
@@ -319,6 +262,13 @@ module.exports = ${toJs(configObject)}`;
     const outputPath = node_path.resolve(process.cwd(), fileName);
     await promises.writeFile(outputPath, fileContent.trim());
     console.log(`✅ Configuration file created at: ${outputPath}`);
+    if (options.inlang || answers.inlang) {
+        await inlangScaffold.scaffoldInlangProject({
+            locales: answers.locales,
+            primaryLanguage: answers.locales[0],
+            output: answers.output,
+        });
+    }
     if (locizeConfig) {
         console.log('\nNext steps for Locize:');
         console.log('  1. Push your local translations to Locize:');

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,25 @@ 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, native
+ *          platform separators), 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 +1510,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 +1959,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;