i18next-cli 1.56.12 → 1.57.0

package/README.md

@@ -25,6 +25,10 @@ A unified, high-performance i18next CLI toolchain, powered by SWC.
 > npx i18next-cli lint
 > ```
 
+## Advice:
+
+If you're looking for a managed backend to pair with `i18next-cli`, take a look at [Locize](https://www.locize.com?utm_source=i18next_cli_readme&utm_medium=github&utm_campaign=readme) — `i18next-cli` already ships with `locize-download`, `locize-sync`, and `locize-migrate` commands. Built by the same team behind i18next, with CDN delivery, AI translation, review workflow, and no redeploys for copy changes.
+
 ## Why i18next-cli?
 
 `i18next-cli` is built from the ground up to meet the demands of modern web development.
@@ -106,6 +110,25 @@ Interactive setup wizard to create your configuration file.
 npx i18next-cli init
 ```
 
+**Options:**
+- `--ci`: Skip the browser launch when a backend (e.g. Locize) is selected;
+  the signup URL is printed instead. Useful for scripted runs. The wizard
+  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.
+
+The wizard asks for the config file type, locales, source-file glob, output
+path, and finally **"Translation backend?"** with three options:
+
+- **Local files only** (default) — keeps the current local-JSON workflow.
+- **Locize** (recommended for team / production workflows) — opens the
+  [Locize](https://www.locize.app) signup page in your browser and then
+  prompts for your Project ID and API key. The wizard writes a `locize`
+  block into the generated config so [`locize-sync`](#locize-integration)
+  works out of the box. The API key prompt can be left empty (read-only
+  mode); add it later via a `LOCIZE_API_KEY` environment variable.
+- **Other / skip** — same as "Local files only" for the wizard's purposes.
+
 ### `extract`
 Parses source files, extracts keys, and updates your JSON translation files.
 
@@ -447,6 +470,12 @@ npx i18next-cli rename-key "Invalid username or password" "login.form.invalid-cr
 
 ### Locize Integration
 
+**First-time setup:** the easiest way to wire up Locize is to run
+`npx i18next-cli init` and pick **Locize** at the "Translation backend?"
+prompt — the wizard will open the signup page, ask for your Project ID
+and API key, and write the `locize` block into your config for you. See
+[the `init` command](#init) for details.
+
 **Prerequisites:** The locize commands require `locize-cli` to be installed:
 
 ```bash

package/dist/cjs/cli.js

@@ -32,7 +32,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.56.12'); // This string is replaced with the actual version at build time by rollup
+    .version('1.57.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
@@ -163,7 +163,8 @@ program
 program
     .command('init')
     .description('Create a new i18next.config.ts/js file with an interactive setup wizard.')
-    .action(init.runInit);
+    .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 }));
 program
     .command('lint')
     .description('Find potential issues like hardcoded strings in your codebase.')

package/dist/cjs/init.js

@@ -3,8 +3,58 @@
 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');
 
+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;
+    }
+}
 /**
  * Determines if the current project is configured as an ESM project.
  * Checks the package.json file for `"type": "module"`.
@@ -92,7 +142,7 @@ async function isTypeScriptProject() {
  * // - i18next.config.js (JavaScript ESM/CommonJS)
  * ```
  */
-async function runInit() {
+async function runInit(options = {}) {
     console.log('Welcome to the i18next-cli setup wizard!');
     console.log('Scanning your project for a recommended configuration...');
     const detectedConfig = await heuristicConfig.detectConfig();
@@ -143,7 +193,49 @@ async function runInit() {
                 ? detectedConfig.extract.output
                 : 'public/locales/{{language}}/{{namespace}}.json',
         },
+        {
+            type: 'select',
+            name: 'backend',
+            message: 'Translation backend?',
+            choices: [
+                { name: 'Local files only', value: 'local' },
+                { name: 'Locize (recommended) — managed backend, CDN delivery, optional AI auto-translate', value: 'locize' },
+                { name: 'Other / skip', value: 'other' },
+            ],
+            default: 'local',
+        },
     ]);
+    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 });
+        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;
+    }
     const isTypeScript = answers.fileType.includes('TypeScript');
     const isEsm = await isEsmProject();
     const fileName = isTypeScript ? 'i18next.config.ts' : 'i18next.config.js';
@@ -154,6 +246,8 @@ async function runInit() {
             output: answers.output,
         },
     };
+    if (locizeConfig)
+        configObject.locize = locizeConfig;
     // Helper to serialize a JS value as a JS literal:
     function toJs(value, indent = 2, level = 0) {
         const pad = (n) => ' '.repeat(n * indent);
@@ -225,6 +319,28 @@ 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 (locizeConfig) {
+        console.log('\nNext steps for Locize:');
+        console.log('  1. Push your local translations to Locize:');
+        console.log('       npx i18next-cli locize-sync');
+        console.log('  2. Find your Project ID and API keys in the Locize UI under:');
+        console.log('       Project Settings → "API, CDN, NOTIFICATIONS" tab (www.locize.app)');
+        if (locizeConfig.apiKey) {
+            console.log('  3. Before committing, move the API key out of the config file into an environment variable:');
+            console.log('       # .env (add to .gitignore)');
+            console.log('       LOCIZE_API_KEY=<paste the key currently in your config>');
+            console.log('       # then in your config:');
+            console.log('       apiKey: process.env.LOCIZE_API_KEY');
+        }
+        else {
+            console.log('  3. Add your API key later via environment variable:');
+            console.log('       # .env (add to .gitignore)');
+            console.log('       LOCIZE_API_KEY=...');
+            console.log('       # then in your config:');
+            console.log('       apiKey: process.env.LOCIZE_API_KEY');
+        }
+        console.log('  4. To enable automatic translation, turn it on in your Locize project settings → "EDITOR, TM/MT/AI, ORDERING" tab (web UI).');
+    }
 }
 
 exports.runInit = runInit;

package/dist/esm/cli.js

@@ -30,7 +30,7 @@ const program = new Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.56.12'); // This string is replaced with the actual version at build time by rollup
+    .version('1.57.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
@@ -161,7 +161,8 @@ program
 program
     .command('init')
     .description('Create a new i18next.config.ts/js file with an interactive setup wizard.')
-    .action(runInit);
+    .option('--ci', 'Skip the browser launch when a backend (e.g. Locize) is selected. The signup URL is printed instead.')
+    .action((options) => runInit({ ci: !!options.ci }));
 program
     .command('lint')
     .description('Find potential issues like hardcoded strings in your codebase.')

package/dist/esm/init.js

@@ -1,8 +1,58 @@
 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';
 
+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;
+    }
+}
 /**
  * Determines if the current project is configured as an ESM project.
  * Checks the package.json file for `"type": "module"`.
@@ -90,7 +140,7 @@ async function isTypeScriptProject() {
  * // - i18next.config.js (JavaScript ESM/CommonJS)
  * ```
  */
-async function runInit() {
+async function runInit(options = {}) {
     console.log('Welcome to the i18next-cli setup wizard!');
     console.log('Scanning your project for a recommended configuration...');
     const detectedConfig = await detectConfig();
@@ -141,7 +191,49 @@ async function runInit() {
                 ? detectedConfig.extract.output
                 : 'public/locales/{{language}}/{{namespace}}.json',
         },
+        {
+            type: 'select',
+            name: 'backend',
+            message: 'Translation backend?',
+            choices: [
+                { name: 'Local files only', value: 'local' },
+                { name: 'Locize (recommended) — managed backend, CDN delivery, optional AI auto-translate', value: 'locize' },
+                { name: 'Other / skip', value: 'other' },
+            ],
+            default: 'local',
+        },
     ]);
+    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 });
+        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;
+    }
     const isTypeScript = answers.fileType.includes('TypeScript');
     const isEsm = await isEsmProject();
     const fileName = isTypeScript ? 'i18next.config.ts' : 'i18next.config.js';
@@ -152,6 +244,8 @@ async function runInit() {
             output: answers.output,
         },
     };
+    if (locizeConfig)
+        configObject.locize = locizeConfig;
     // Helper to serialize a JS value as a JS literal:
     function toJs(value, indent = 2, level = 0) {
         const pad = (n) => ' '.repeat(n * indent);
@@ -223,6 +317,28 @@ module.exports = ${toJs(configObject)}`;
     const outputPath = resolve(process.cwd(), fileName);
     await writeFile(outputPath, fileContent.trim());
     console.log(`✅ Configuration file created at: ${outputPath}`);
+    if (locizeConfig) {
+        console.log('\nNext steps for Locize:');
+        console.log('  1. Push your local translations to Locize:');
+        console.log('       npx i18next-cli locize-sync');
+        console.log('  2. Find your Project ID and API keys in the Locize UI under:');
+        console.log('       Project Settings → "API, CDN, NOTIFICATIONS" tab (www.locize.app)');
+        if (locizeConfig.apiKey) {
+            console.log('  3. Before committing, move the API key out of the config file into an environment variable:');
+            console.log('       # .env (add to .gitignore)');
+            console.log('       LOCIZE_API_KEY=<paste the key currently in your config>');
+            console.log('       # then in your config:');
+            console.log('       apiKey: process.env.LOCIZE_API_KEY');
+        }
+        else {
+            console.log('  3. Add your API key later via environment variable:');
+            console.log('       # .env (add to .gitignore)');
+            console.log('       LOCIZE_API_KEY=...');
+            console.log('       # then in your config:');
+            console.log('       apiKey: process.env.LOCIZE_API_KEY');
+        }
+        console.log('  4. To enable automatic translation, turn it on in your Locize project settings → "EDITOR, TM/MT/AI, ORDERING" tab (web UI).');
+    }
 }
 
 export { runInit };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next-cli",
-  "version": "1.56.12",
+  "version": "1.57.0",
   "description": "A unified, high-performance i18next CLI.",
   "type": "module",
   "bin": {

package/types/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAoBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AAiZ7B,OAAO,EAAE,OAAO,EAAE,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAoBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AAkZ7B,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/types/init.d.ts

@@ -25,5 +25,7 @@
  * // - i18next.config.js (JavaScript ESM/CommonJS)
  * ```
  */
-export declare function runInit(): Promise<void>;
+export declare function runInit(options?: {
+    ci?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/types/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,kBAyI5B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAkHA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAE,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,iBA6M5D"}