i18next-cli 1.61.1 → 1.62.0

package/dist/cjs/types-generator.js

@@ -13,6 +13,11 @@ var json5Parser = require('@croct/json5-parser');
 var yaml = require('yaml');
 var vm = require('node:vm');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var yaml__default = /*#__PURE__*/_interopDefault(yaml);
+var vm__default = /*#__PURE__*/_interopDefault(vm);
+
 async function loadFile(file) {
     const ext = node_path.extname(file);
     if (['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].includes(ext)) {
@@ -31,14 +36,14 @@ async function loadFile(file) {
         });
         const exports = {};
         const module = { exports };
-        const context = vm.createContext({
+        const context = vm__default.default.createContext({
             exports,
             module,
             require: (id) => require(id),
             console,
             process
         });
-        const script = new vm.Script(code, { filename: file });
+        const script = new vm__default.default.Script(code, { filename: file });
         script.runInContext(context);
         // @ts-ignore
         const exported = context.module.exports?.default || context.module.exports;
@@ -46,7 +51,7 @@ async function loadFile(file) {
     }
     const content = await promises.readFile(file, 'utf-8');
     if (ext === '.yaml' || ext === '.yml') {
-        return yaml.parse(content);
+        return yaml__default.default.parse(content);
     }
     if (ext === '.json5') {
         return json5Parser.JsonParser.parse(content, json5Parser.JsonObjectNode).toJSON();

package/dist/cjs/utils/file-utils.js

@@ -7,6 +7,10 @@ var config = require('../config.js');
 var json5Parser = require('@croct/json5-parser');
 var yaml = require('yaml');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var yaml__default = /*#__PURE__*/_interopDefault(yaml);
+
 /**
  * Thrown when an existing translation file in a structured data format
  * (JSON/JSON5/YAML) exists on disk but cannot be parsed. Callers should treat
@@ -97,7 +101,7 @@ async function loadTranslationFile(filePath) {
     else if (ext === '.yaml' || ext === '.yml') {
         const content = await promises.readFile(fullPath, 'utf-8');
         try {
-            return yaml.parse(content);
+            return yaml__default.default.parse(content);
         }
         catch (error) {
             throw new ParseTranslationFileError(filePath, error);
@@ -165,7 +169,7 @@ function serializeTranslationFile(data, format = 'json', indentation = 2, rawCon
             return node.toString({ object: { indentationSize: Number(indentation) ?? 2 } });
         }
         case 'yaml':
-            return yaml.stringify(data, { indent: Number(indentation) || 2, lineWidth: 0 });
+            return yaml__default.default.stringify(data, { indent: Number(indentation) || 2, lineWidth: 0 });
         case 'js':
         case 'js-esm':
             return `export default ${jsonString};\n`;

package/dist/cjs/utils/locize-onboarding.js

@@ -0,0 +1,91 @@
+'use strict';
+
+var inquirer = require('inquirer');
+var execa = require('execa');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var inquirer__default = /*#__PURE__*/_interopDefault(inquirer);
+
+/** 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;
+    }
+}
+/**
+ * Prompts for Locize credentials (Project ID + optional API key) and returns them.
+ * Warns (but does not block) when the Project ID does not look like a UUID.
+ */
+async function promptLocizeCredentials() {
+    const credentials = await inquirer__default.default.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.
+    const result = { projectId: credentials.projectId };
+    if (credentials.apiKey)
+        result.apiKey = credentials.apiKey;
+    return result;
+}
+
+exports.UUID_SHAPE = UUID_SHAPE;
+exports.openBrowser = openBrowser;
+exports.promptLocizeCredentials = promptLocizeCredentials;

package/dist/cjs/utils/wrap-ora.js

@@ -2,6 +2,10 @@
 
 var ora = require('ora');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var ora__default = /*#__PURE__*/_interopDefault(ora);
+
 /**
  * Creates a spinner-like object that either:
  * - is fully silent (quiet mode),
@@ -16,7 +20,7 @@ function createSpinnerLike(initialText, options = {}) {
     // If interactive (no logger and not quiet), create a single real ora spinner
     let realSpinner = null;
     if (!quiet && !logger) {
-        realSpinner = ora({ text }).start();
+        realSpinner = ora__default.default({ text }).start();
     }
     const self = {
         get text() { return text; },
@@ -40,7 +44,7 @@ function createSpinnerLike(initialText, options = {}) {
             }
             else {
                 if (!realSpinner)
-                    realSpinner = ora({ text }).start();
+                    realSpinner = ora__default.default({ text }).start();
                 realSpinner.succeed(message);
             }
         },
@@ -58,7 +62,7 @@ function createSpinnerLike(initialText, options = {}) {
             }
             else {
                 if (!realSpinner)
-                    realSpinner = ora({ text }).start();
+                    realSpinner = ora__default.default({ text }).start();
                 realSpinner.fail(message);
             }
         },
@@ -76,7 +80,7 @@ function createSpinnerLike(initialText, options = {}) {
             }
             else {
                 if (!realSpinner)
-                    realSpinner = ora({ text }).start();
+                    realSpinner = ora__default.default({ text }).start();
                 try {
                     realSpinner.warn?.(message);
                 }
@@ -101,7 +105,7 @@ function createSpinnerLike(initialText, options = {}) {
             }
             else {
                 if (!realSpinner)
-                    realSpinner = ora({ text }).start();
+                    realSpinner = ora__default.default({ text }).start();
                 realSpinner.text = String(msg);
             }
         }

package/dist/esm/cli.js

@@ -25,12 +25,13 @@ import { runRenameKey } from './rename-key.js';
 import { runInstrumenter } from './instrumenter/core/instrumenter.js';
 import './utils/jsx-attributes.js';
 import 'magic-string';
+import { runLocalize } from './localize/localize.js';
 
 const program = new 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.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
@@ -284,6 +285,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 runLocalize(options, cfgPath);
+    }
+    catch (error) {
+        console.error(styleText('red', 'Error running localize command:'), error);
+        process.exit(1);
+    }
+});
 program
     .command('locize-sync')
     .description('Synchronize local translations with your Locize project.')
@@ -292,6 +316,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 = await ensureConfig(cfgPath);

package/dist/esm/index.js

@@ -11,3 +11,7 @@ export { runRenameKey } from './rename-key.js';
 export { runInstrumenter, writeExtractedKeys } from './instrumenter/core/instrumenter.js';
 import './utils/jsx-attributes.js';
 import 'magic-string';
+export { runLocalize } from './localize/localize.js';
+import 'node:fs/promises';
+import 'node:path';
+export { AGENT_PROMPT } from './localize/agent-prompt.js';

package/dist/esm/init.js

@@ -1,58 +1,10 @@
 import inquirer from 'inquirer';
 import { writeFile, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { execa } from 'execa';
 import { detectConfig } from './heuristic-config.js';
+import { openBrowser, promptLocizeCredentials } from './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('open', [url], { stdio: 'ignore' });
-        }
-        else if (process.platform === 'win32') {
-            // `start` is a cmd.exe builtin; the empty "" is the window-title slot
-            await 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('wslview', [url], { stdio: 'ignore' });
-            }
-            catch {
-                try {
-                    await execa('wsl-open', [url], { stdio: 'ignore' });
-                }
-                catch {
-                    await execa('xdg-open', [url], { stdio: 'ignore' });
-                }
-            }
-        }
-        else {
-            await execa('xdg-open', [url], { stdio: 'ignore' });
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+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"`.
@@ -210,29 +162,7 @@ async function runInit(options = {}) {
         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 promptLocizeCredentials();
     }
     const isTypeScript = answers.fileType.includes('TypeScript');
     const isEsm = await isEsmProject();

package/dist/esm/instrumenter/core/instrumenter.js

@@ -1460,6 +1460,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(join(cwd, dir, name))) {
+                return 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).
@@ -1485,13 +1503,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(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 {
@@ -1939,4 +1952,4 @@ async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugin
     return candidates;
 }
 
-export { runInstrumenter, writeExtractedKeys };
+export { detectProjectEnvironment, findExistingI18nInitFile, isProjectUsingReact, isProjectUsingTypeScript, runInstrumenter, writeExtractedKeys };

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

@@ -0,0 +1,47 @@
+/**
+ * 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.
+`;
+
+export { AGENT_PROMPT };

package/dist/esm/localize/detect.js

@@ -0,0 +1,85 @@
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageDeps() {
+    try {
+        const content = await readFile(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(join(cwd, 'app')) || await pathExists(join(cwd, 'src', 'app')));
+    const hasParaglide = has('@inlang/paraglide-js') || await pathExists(join(cwd, 'project.inlang'));
+    return {
+        framework,
+        hasI18next: has('i18next') || has('react-i18next'),
+        hasTypeScript: await pathExists(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));
+    });
+}
+
+export { detectStack, hasStackPlugin };