i18next-cli 1.47.9 → 1.47.11

package/README.md

@@ -249,7 +249,7 @@ npx i18next-cli lint
 
 ### `instrument`
 
-Scans your source code for hardcoded user-facing strings and instruments them with i18next translation calls. This is useful for adding i18next instrumentation to an existing codebase that wasn't built with internationalization in mind.
+Scans your source code for hardcoded user-facing strings and instruments them with i18next translation calls. This is useful for adding i18next instrumentation to an existing codebase that wasn't built with internationalization in mind. You can see this in action in [this video](https://youtu.be/aWZnZXwGg34) or in [this blog post](https://www.locize.com/blog/i18next-cli-instrument).
 
 > **⚠️ First-Step Tool:** The `instrument` command uses heuristic-based detection and is designed as a **first pass** to identify and suggest transformation candidates. It will **not catch 100% of cases**, and you should expect both false positives and false negatives. Always review the suggested transformations carefully before committing them to your codebase. Think of it as an intelligent code assistant, not an automated compiler.
 

package/dist/cjs/cli.js

@@ -31,7 +31,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.47.9'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.11'); // 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

package/dist/cjs/extractor/parsers/scope-manager.js

@@ -11,6 +11,40 @@ class ScopeManager {
     constructor(config) {
         this.config = config;
     }
+    /**
+     * Recursively unwraps TypeScript type assertion wrappers to reach the
+     * underlying expression node.
+     */
+    static unwrapTsExpression(node) {
+        if (!node)
+            return node;
+        switch (node.type) {
+            case 'TsConstAssertion':
+            case 'TsAsExpression':
+            case 'TsSatisfiesExpression':
+                return ScopeManager.unwrapTsExpression(node.expression);
+            default:
+                return node;
+        }
+    }
+    /**
+     * Extracts a string value from a variable declarator's TypeScript type
+     * annotation when it is a literal string type (e.g., `const ns: 'users'`).
+     */
+    static extractStringFromTypeAnnotation(node) {
+        if (!node?.id || node.id.type !== 'Identifier')
+            return undefined;
+        if ('typeAnnotation' in node.id) {
+            const rawTypeAnn = node.id.typeAnnotation;
+            if (!rawTypeAnn)
+                return undefined;
+            const tsType = rawTypeAnn.typeAnnotation;
+            if (tsType?.type === 'TsLiteralType' && tsType.literal?.type === 'StringLiteral') {
+                return tsType.literal.value;
+            }
+        }
+        return undefined;
+    }
     /**
      * Reset per-file scope state.
      *
@@ -115,9 +149,20 @@ class ScopeManager {
         const init = node.init;
         if (!init)
             return;
-        // Record simple const/let string initializers for later resolution
-        if (node.id.type === 'Identifier' && init.type === 'StringLiteral') {
-            this.simpleConstants.set(node.id.value, init.value);
+        // Record simple const/let string initializers for later resolution.
+        // Unwrap TS type assertion wrappers (as const, satisfies, as 'x') and fall
+        // back to the variable's type annotation when the init is not a string literal.
+        if (node.id.type === 'Identifier') {
+            const unwrapped = ScopeManager.unwrapTsExpression(init);
+            if (unwrapped?.type === 'StringLiteral') {
+                this.simpleConstants.set(node.id.value, unwrapped.value);
+            }
+            else {
+                const fromType = ScopeManager.extractStringFromTypeAnnotation(node);
+                if (fromType !== undefined) {
+                    this.simpleConstants.set(node.id.value, fromType);
+                }
+            }
             // continue processing; still may be a useTranslation/getFixedT call below
         }
         // Determine the actual call expression, looking inside AwaitExpressions.

package/dist/cjs/locize.js

@@ -7,29 +7,37 @@ var inquirer = require('inquirer');
 var node_path = require('node:path');
 
 /**
- * Verifies that the locize-cli tool is installed and accessible.
+ * Resolves the locize-cli executable to use.
  *
- * @throws Exits the process with error code 1 if locize-cli is not found
+ * Tries, in order:
+ * 1. A locally / globally installed `locize` binary
+ * 2. Falls back to `npx locize-cli` so it can be fetched on demand
  *
- * @example
- * ```typescript
- * await checkLocizeCliExists()
- * // Continues execution if locize-cli is available
- * // Otherwise exits with installation instructions
- * ```
+ * If neither works the process exits with an error.
+ *
+ * @returns An object with `cmd` (the executable) and `prefixArgs` (extra args
+ *          to prepend before the locize sub-command, e.g. `['locize-cli']`
+ *          when running through npx).
  */
-async function checkLocizeCliExists() {
+async function resolveLocizeBin() {
+    // 1. Try a locally / globally installed binary
     try {
         await execa.execa('locize', ['--version']);
+        return { cmd: 'locize', prefixArgs: [] };
     }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            console.error(node_util.styleText('red', 'Error: `locize-cli` command not found.'));
-            console.log(node_util.styleText('yellow', 'Please install it globally to use the Locize integration:'));
-            console.log(node_util.styleText('cyan', 'npm install -g locize-cli'));
-            process.exit(1);
-        }
+    catch {
+        // not found – continue
+    }
+    // 2. Fall back to npx
+    try {
+        console.log(node_util.styleText('yellow', '`locize` command not found – trying npx...'));
+        await execa.execa('npx', ['locize-cli', '--version']);
+        return { cmd: 'npx', prefixArgs: ['locize-cli'] };
     }
+    catch {
+        // npx also failed
+    }
+    return null;
 }
 /**
  * Interactive setup wizard for configuring Locize credentials.
@@ -236,14 +244,23 @@ function buildArgs(command, config, cliOptions) {
  * ```
  */
 async function runLocizeCommand(command, config, cliOptions = {}) {
-    await checkLocizeCliExists();
+    const resolved = await resolveLocizeBin();
+    if (!resolved) {
+        console.error(node_util.styleText('red', 'Error: `locize-cli` command not found.'));
+        console.log(node_util.styleText('yellow', 'Please install it to use the Locize integration:'));
+        console.log(node_util.styleText('cyan', '  npm install -g locize-cli'));
+        console.log(node_util.styleText('yellow', 'Or make sure npx is available so it can be fetched on demand.'));
+        process.exit(1);
+        return;
+    }
+    const { cmd, prefixArgs } = resolved;
     const spinner = ora(`Running 'locize ${command}'...\n`).start();
     let effectiveConfig = config;
     try {
         // 1. First attempt
-        const initialArgs = buildArgs(command, effectiveConfig, cliOptions);
-        console.log(node_util.styleText('cyan', `\nRunning 'locize ${maskArgs(initialArgs).join(' ')}'...`));
-        const result = await execa.execa('locize', initialArgs, { stdio: 'pipe' });
+        const initialArgs = [...prefixArgs, ...buildArgs(command, effectiveConfig, cliOptions)];
+        console.log(node_util.styleText('cyan', `\nRunning 'locize ${maskArgs(initialArgs.slice(prefixArgs.length)).join(' ')}'...`));
+        const result = await execa.execa(cmd, initialArgs, { stdio: 'pipe' });
         spinner.succeed(node_util.styleText('green', `'locize ${command}' completed successfully.`));
         if (result?.stdout)
             console.log(result.stdout); // Print captured output on success
@@ -259,9 +276,9 @@ async function runLocizeCommand(command, config, cliOptions = {}) {
                 spinner.start('Retrying with new credentials...');
                 try {
                     // 3. Retry attempt, rebuilding args with the NOW-UPDATED currentConfig object
-                    const retryArgs = buildArgs(command, effectiveConfig, cliOptions);
-                    console.log(node_util.styleText('cyan', `\nRunning 'locize ${maskArgs(retryArgs).join(' ')}'...`));
-                    const result = await execa.execa('locize', retryArgs, { stdio: 'pipe' });
+                    const retryArgs = [...prefixArgs, ...buildArgs(command, effectiveConfig, cliOptions)];
+                    console.log(node_util.styleText('cyan', `\nRunning 'locize ${maskArgs(retryArgs.slice(prefixArgs.length)).join(' ')}'...`));
+                    const result = await execa.execa(cmd, retryArgs, { stdio: 'pipe' });
                     spinner.succeed(node_util.styleText('green', 'Retry successful!'));
                     if (result?.stdout)
                         console.log(result.stdout);

package/dist/esm/cli.js

@@ -29,7 +29,7 @@ const program = new Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.47.9'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.11'); // 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

package/dist/esm/extractor/parsers/scope-manager.js

@@ -9,6 +9,40 @@ class ScopeManager {
     constructor(config) {
         this.config = config;
     }
+    /**
+     * Recursively unwraps TypeScript type assertion wrappers to reach the
+     * underlying expression node.
+     */
+    static unwrapTsExpression(node) {
+        if (!node)
+            return node;
+        switch (node.type) {
+            case 'TsConstAssertion':
+            case 'TsAsExpression':
+            case 'TsSatisfiesExpression':
+                return ScopeManager.unwrapTsExpression(node.expression);
+            default:
+                return node;
+        }
+    }
+    /**
+     * Extracts a string value from a variable declarator's TypeScript type
+     * annotation when it is a literal string type (e.g., `const ns: 'users'`).
+     */
+    static extractStringFromTypeAnnotation(node) {
+        if (!node?.id || node.id.type !== 'Identifier')
+            return undefined;
+        if ('typeAnnotation' in node.id) {
+            const rawTypeAnn = node.id.typeAnnotation;
+            if (!rawTypeAnn)
+                return undefined;
+            const tsType = rawTypeAnn.typeAnnotation;
+            if (tsType?.type === 'TsLiteralType' && tsType.literal?.type === 'StringLiteral') {
+                return tsType.literal.value;
+            }
+        }
+        return undefined;
+    }
     /**
      * Reset per-file scope state.
      *
@@ -113,9 +147,20 @@ class ScopeManager {
         const init = node.init;
         if (!init)
             return;
-        // Record simple const/let string initializers for later resolution
-        if (node.id.type === 'Identifier' && init.type === 'StringLiteral') {
-            this.simpleConstants.set(node.id.value, init.value);
+        // Record simple const/let string initializers for later resolution.
+        // Unwrap TS type assertion wrappers (as const, satisfies, as 'x') and fall
+        // back to the variable's type annotation when the init is not a string literal.
+        if (node.id.type === 'Identifier') {
+            const unwrapped = ScopeManager.unwrapTsExpression(init);
+            if (unwrapped?.type === 'StringLiteral') {
+                this.simpleConstants.set(node.id.value, unwrapped.value);
+            }
+            else {
+                const fromType = ScopeManager.extractStringFromTypeAnnotation(node);
+                if (fromType !== undefined) {
+                    this.simpleConstants.set(node.id.value, fromType);
+                }
+            }
             // continue processing; still may be a useTranslation/getFixedT call below
         }
         // Determine the actual call expression, looking inside AwaitExpressions.

package/dist/esm/locize.js

@@ -5,29 +5,37 @@ import inquirer from 'inquirer';
 import { sep, resolve } from 'node:path';
 
 /**
- * Verifies that the locize-cli tool is installed and accessible.
+ * Resolves the locize-cli executable to use.
  *
- * @throws Exits the process with error code 1 if locize-cli is not found
+ * Tries, in order:
+ * 1. A locally / globally installed `locize` binary
+ * 2. Falls back to `npx locize-cli` so it can be fetched on demand
  *
- * @example
- * ```typescript
- * await checkLocizeCliExists()
- * // Continues execution if locize-cli is available
- * // Otherwise exits with installation instructions
- * ```
+ * If neither works the process exits with an error.
+ *
+ * @returns An object with `cmd` (the executable) and `prefixArgs` (extra args
+ *          to prepend before the locize sub-command, e.g. `['locize-cli']`
+ *          when running through npx).
  */
-async function checkLocizeCliExists() {
+async function resolveLocizeBin() {
+    // 1. Try a locally / globally installed binary
     try {
         await execa('locize', ['--version']);
+        return { cmd: 'locize', prefixArgs: [] };
     }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            console.error(styleText('red', 'Error: `locize-cli` command not found.'));
-            console.log(styleText('yellow', 'Please install it globally to use the Locize integration:'));
-            console.log(styleText('cyan', 'npm install -g locize-cli'));
-            process.exit(1);
-        }
+    catch {
+        // not found – continue
+    }
+    // 2. Fall back to npx
+    try {
+        console.log(styleText('yellow', '`locize` command not found – trying npx...'));
+        await execa('npx', ['locize-cli', '--version']);
+        return { cmd: 'npx', prefixArgs: ['locize-cli'] };
     }
+    catch {
+        // npx also failed
+    }
+    return null;
 }
 /**
  * Interactive setup wizard for configuring Locize credentials.
@@ -234,14 +242,23 @@ function buildArgs(command, config, cliOptions) {
  * ```
  */
 async function runLocizeCommand(command, config, cliOptions = {}) {
-    await checkLocizeCliExists();
+    const resolved = await resolveLocizeBin();
+    if (!resolved) {
+        console.error(styleText('red', 'Error: `locize-cli` command not found.'));
+        console.log(styleText('yellow', 'Please install it to use the Locize integration:'));
+        console.log(styleText('cyan', '  npm install -g locize-cli'));
+        console.log(styleText('yellow', 'Or make sure npx is available so it can be fetched on demand.'));
+        process.exit(1);
+        return;
+    }
+    const { cmd, prefixArgs } = resolved;
     const spinner = ora(`Running 'locize ${command}'...\n`).start();
     let effectiveConfig = config;
     try {
         // 1. First attempt
-        const initialArgs = buildArgs(command, effectiveConfig, cliOptions);
-        console.log(styleText('cyan', `\nRunning 'locize ${maskArgs(initialArgs).join(' ')}'...`));
-        const result = await execa('locize', initialArgs, { stdio: 'pipe' });
+        const initialArgs = [...prefixArgs, ...buildArgs(command, effectiveConfig, cliOptions)];
+        console.log(styleText('cyan', `\nRunning 'locize ${maskArgs(initialArgs.slice(prefixArgs.length)).join(' ')}'...`));
+        const result = await execa(cmd, initialArgs, { stdio: 'pipe' });
         spinner.succeed(styleText('green', `'locize ${command}' completed successfully.`));
         if (result?.stdout)
             console.log(result.stdout); // Print captured output on success
@@ -257,9 +274,9 @@ async function runLocizeCommand(command, config, cliOptions = {}) {
                 spinner.start('Retrying with new credentials...');
                 try {
                     // 3. Retry attempt, rebuilding args with the NOW-UPDATED currentConfig object
-                    const retryArgs = buildArgs(command, effectiveConfig, cliOptions);
-                    console.log(styleText('cyan', `\nRunning 'locize ${maskArgs(retryArgs).join(' ')}'...`));
-                    const result = await execa('locize', retryArgs, { stdio: 'pipe' });
+                    const retryArgs = [...prefixArgs, ...buildArgs(command, effectiveConfig, cliOptions)];
+                    console.log(styleText('cyan', `\nRunning 'locize ${maskArgs(retryArgs.slice(prefixArgs.length)).join(' ')}'...`));
+                    const result = await execa(cmd, retryArgs, { stdio: 'pipe' });
                     spinner.succeed(styleText('green', 'Retry successful!'));
                     if (result?.stdout)
                         console.log(result.stdout);

package/package.json

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

package/types/extractor/parsers/scope-manager.d.ts

@@ -6,6 +6,16 @@ export declare class ScopeManager {
     private scope;
     private simpleConstants;
     constructor(config: Omit<I18nextToolkitConfig, 'plugins'>);
+    /**
+     * Recursively unwraps TypeScript type assertion wrappers to reach the
+     * underlying expression node.
+     */
+    private static unwrapTsExpression;
+    /**
+     * Extracts a string value from a variable declarator's TypeScript type
+     * annotation when it is a literal string type (e.g., `const ns: 'users'`).
+     */
+    private static extractStringFromTypeAnnotation;
     /**
      * Reset per-file scope state.
      *

package/types/extractor/parsers/scope-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-manager.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/scope-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAmC,MAAM,WAAW,CAAA;AACpF,OAAO,KAAK,EAAE,SAAS,EAA4B,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAG5F,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,KAAK,CAAqE;IAGlF,OAAO,CAAC,eAAe,CAAiC;gBAE3C,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC;IAI1D;;;;;;OAMG;IACI,KAAK,IAAK,IAAI;IAMrB;;;OAGG;IACH,UAAU,IAAK,IAAI;IAInB;;;OAGG;IACH,SAAS,IAAK,IAAI;IAIlB;;;;;;OAMG;IACH,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAUnD;;;;;;OAMG;IACH,eAAe,CAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAkBrD,OAAO,CAAC,uBAAuB;IAoB/B;;OAEG;IACI,6BAA6B,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIvE;;;;;;;;;;OAUG;IACH,wBAAwB,CAAE,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAuDzD;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IAsGvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,8BAA8B;IA+EtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB;IAoBjC;;;;;;;;;OASG;IACH,OAAO,CAAC,qCAAqC;CAuB9C"}
+{"version":3,"file":"scope-manager.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/scope-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAMnB,MAAM,WAAW,CAAA;AAClB,OAAO,KAAK,EAAE,SAAS,EAA4B,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAG5F,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,KAAK,CAAqE;IAGlF,OAAO,CAAC,eAAe,CAAiC;gBAE3C,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC;IAI1D;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAcjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,+BAA+B;IAgB9C;;;;;;OAMG;IACI,KAAK,IAAK,IAAI;IAMrB;;;OAGG;IACH,UAAU,IAAK,IAAI;IAInB;;;OAGG;IACH,SAAS,IAAK,IAAI;IAIlB;;;;;;OAMG;IACH,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAUnD;;;;;;OAMG;IACH,eAAe,CAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAkBrD,OAAO,CAAC,uBAAuB;IAoB/B;;OAEG;IACI,6BAA6B,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIvE;;;;;;;;;;OAUG;IACH,wBAAwB,CAAE,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAiEzD;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IAsGvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,8BAA8B;IA+EtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB;IAoBjC;;;;;;;;;OASG;IACH,OAAO,CAAC,qCAAqC;CAuB9C"}

package/types/locize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locize.d.ts","sourceRoot":"","sources":["../src/locize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AA8RnD,eAAO,MAAM,aAAa,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAiD,CAAA;AAC7H,eAAO,MAAM,iBAAiB,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAqD,CAAA;AACrI,eAAO,MAAM,gBAAgB,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAoD,CAAA"}
+{"version":3,"file":"locize.d.ts","sourceRoot":"","sources":["../src/locize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAgTnD,eAAO,MAAM,aAAa,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAiD,CAAA;AAC7H,eAAO,MAAM,iBAAiB,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAqD,CAAA;AACrI,eAAO,MAAM,gBAAgB,GAAI,QAAQ,oBAAoB,EAAE,aAAa,GAAG,kBAAoD,CAAA"}