i18next-cli 1.34.0 → 1.34.1

package/dist/esm/utils/default-value.js

@@ -1 +1,41 @@
-function t(t,r,n,e,u){if("function"==typeof t)try{return t(r,n,e,u||r)}catch(t){return""}return t||""}export{t as resolveDefaultValue};
+/**
+ * Resolves the default value for a missing key in secondary languages.
+ * Supports both string and function-based default values.
+ *
+ * @param defaultValue - The configured default value (string or function)
+ * @param key - The translation key
+ * @param namespace - The namespace for the key
+ * @param language - The target language
+ * @returns The resolved default value
+ *
+ * @example
+ * ```typescript
+ * // String-based default value
+ * const result1 = resolveDefaultValue('[MISSING]', 'user.name', 'common', 'de', 'Alice')
+ * // Returns: '[MISSING]'
+ *
+ * // Function-based default value
+ * const defaultValueFn = (key, ns, lang) => `${lang.toUpperCase()}_${ns}_${key}`
+ * const result2 = resolveDefaultValue(defaultValueFn, 'user.name', 'common', 'de', 'Alice')
+ * // Returns: 'DE_common_user.name_Alice'
+ *
+ * // Error handling - function throws
+ * const errorFn = () => { throw new Error('Oops') }
+ * const result3 = resolveDefaultValue(errorFn, 'user.name', 'common', 'de', 'Alice')
+ * // Returns: '' (fallback to empty string)
+ * ```
+ */
+function resolveDefaultValue(defaultValue, key, namespace, language, value) {
+    if (typeof defaultValue === 'function') {
+        try {
+            return defaultValue(key, namespace, language, value || key);
+        }
+        catch (error) {
+            // If the function throws an error, fall back to empty string
+            return '';
+        }
+    }
+    return defaultValue || '';
+}
+
+export { resolveDefaultValue };

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

@@ -1 +1,131 @@
-import{access as t,readFile as n}from"node:fs/promises";import{resolve as r,normalize as e,extname as o}from"node:path";import{createJiti as a}from"jiti";import{getTsConfigAliases as s}from"../config.js";import{JsonParser as c,JsonObjectNode as i}from"@croct/json5-parser";function u(t,n,r){if(!t)return e(`locales/${n}/${r??"translation"}.json`);if("function"==typeof t)try{const o=String(t(n,r));return e(o.replace(/\/\/+/g,"/"))}catch{return e(`locales/${n}/${r??"translation"}.json`)}let o=String(t);return o=o.replace(/\{\{language\}\}|\{\{lng\}\}/g,n),o=null!=r?o.replace(/\{\{namespace\}\}/g,r):o.replace(/\/?\{\{namespace\}\}/g,""),o=o.replace(/\/\/+/g,"/"),e(o)}async function l(e){const u=r(process.cwd(),e);try{await t(u)}catch{return null}try{const t=o(u).toLowerCase();if(".json5"===t){const t=await n(u,"utf-8");return c.parse(t,i).toJSON()}if(".json"===t){const t=await n(u,"utf-8");return JSON.parse(t)}if(".ts"===t||".js"===t){const t=await s(),n=a(process.cwd(),{alias:t,interopDefault:!0});return await n.import(u,{default:!0})}return null}catch(t){return console.warn(`Could not parse translation file ${e}:`,t),null}}async function p(e){const o=r(process.cwd(),e);try{return await t(o),await n(o,"utf-8")}catch{return null}}function f(t,n="json",r=2,e){const o=JSON.stringify(t,null,r);switch(n){case"json5":if(e){const n=c.parse(e,i);return n.update(t),n.toString({object:{indentationSize:Number(r)??2}})}return c.parse(o,i).toString({object:{indentationSize:Number(r)??2}});case"js":case"js-esm":return`export default ${o};\n`;case"js-cjs":return`module.exports = ${o};\n`;case"ts":return`export default ${o} as const;\n`;default:return`${o}\n`}}export{u as getOutputPath,p as loadRawJson5Content,l as loadTranslationFile,f as serializeTranslationFile};
+import { access, readFile } from 'node:fs/promises';
+import { resolve, normalize, extname } from 'node:path';
+import { createJiti } from 'jiti';
+import { getTsConfigAliases } from '../config.js';
+import { JsonParser, JsonObjectNode } from '@croct/json5-parser';
+
+/**
+ * Resolve an output template (string or function) into an actual path string.
+ *
+ * - If `outputTemplate` is a function, call it with (language, namespace)
+ * - If it's a string, replace placeholders:
+ *    - {{language}} or {{lng}} -> language
+ *    - {{namespace}} -> namespace (or removed if namespace is undefined)
+ * - Normalizes duplicate slashes and returns a platform-correct path.
+ */
+function getOutputPath(outputTemplate, language, namespace) {
+    if (!outputTemplate) {
+        // Fallback to a sensible default
+        return normalize(`locales/${language}/${namespace ?? 'translation'}.json`);
+    }
+    if (typeof outputTemplate === 'function') {
+        try {
+            const result = String(outputTemplate(language, namespace));
+            return normalize(result.replace(/\/\/+/g, '/'));
+        }
+        catch {
+            // If user function throws, fallback to default path
+            return normalize(`locales/${language}/${namespace ?? 'translation'}.json`);
+        }
+    }
+    // It's a string template
+    let out = String(outputTemplate);
+    out = out.replace(/\{\{language\}\}|\{\{lng\}\}/g, language);
+    if (namespace !== undefined && namespace !== null) {
+        out = out.replace(/\{\{namespace\}\}/g, namespace);
+    }
+    else {
+        // remove any occurrences of /{{namespace}} or {{namespace}} (keeping surrounding slashes tidy)
+        out = out.replace(/\/?\{\{namespace\}\}/g, '');
+    }
+    // collapse duplicate slashes and normalize to platform-specific separators
+    out = out.replace(/\/\/+/g, '/');
+    return normalize(out);
+}
+/**
+ * Dynamically loads a translation file, supporting .json, .js, and .ts formats.
+ * @param filePath - The path to the translation file.
+ * @returns The parsed content of the file, or null if not found or failed to parse.
+ */
+async function loadTranslationFile(filePath) {
+    const fullPath = resolve(process.cwd(), filePath);
+    try {
+        await access(fullPath);
+    }
+    catch {
+        return null; // File doesn't exist
+    }
+    try {
+        const ext = extname(fullPath).toLowerCase();
+        if (ext === '.json5') {
+            const content = await readFile(fullPath, 'utf-8');
+            // Parse as a JSON5 object node
+            const node = JsonParser.parse(content, JsonObjectNode);
+            return node.toJSON();
+        }
+        else if (ext === '.json') {
+            const content = await readFile(fullPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        else if (ext === '.ts' || ext === '.js') {
+            // Load TypeScript path aliases for proper module resolution
+            const aliases = await getTsConfigAliases();
+            const jiti = createJiti(process.cwd(), {
+                alias: aliases,
+                interopDefault: true,
+            });
+            const module = await jiti.import(fullPath, { default: true });
+            return module;
+        }
+        return null; // Unsupported file type
+    }
+    catch (error) {
+        console.warn(`Could not parse translation file ${filePath}:`, error);
+        return null;
+    }
+}
+// Helper to load raw JSON5 content for preservation
+async function loadRawJson5Content(filePath) {
+    const fullPath = resolve(process.cwd(), filePath);
+    try {
+        await access(fullPath);
+        return await readFile(fullPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serializes a translation object into a string based on the desired format.
+ * For JSON5, preserves comments and formatting using JsonObjectNode.update().
+ */
+function serializeTranslationFile(data, format = 'json', indentation = 2, rawContent // Pass raw content for JSON5 preservation
+) {
+    const jsonString = JSON.stringify(data, null, indentation);
+    switch (format) {
+        case 'json5': {
+            if (rawContent) {
+                // Parse the original JSON5 file, update it, and output as string
+                const node = JsonParser.parse(rawContent, JsonObjectNode);
+                node.update(data);
+                return node.toString({ object: { indentationSize: Number(indentation) ?? 2 } });
+            }
+            // Fallback: create a new node by parsing the generated JSON string and output as string
+            const node = JsonParser.parse(jsonString, JsonObjectNode);
+            return node.toString({ object: { indentationSize: Number(indentation) ?? 2 } });
+        }
+        case 'js':
+        case 'js-esm':
+            return `export default ${jsonString};\n`;
+        case 'js-cjs':
+            return `module.exports = ${jsonString};\n`;
+        case 'ts':
+            // Using `as const` provides better type inference for TypeScript users
+            return `export default ${jsonString} as const;\n`;
+        case 'json':
+        default:
+            return `${jsonString}\n`;
+    }
+}
+
+export { getOutputPath, loadRawJson5Content, loadTranslationFile, serializeTranslationFile };

package/dist/esm/utils/funnel-msg-tracker.js

@@ -1 +1,72 @@
-import{join as t}from"node:path";import{tmpdir as n}from"node:os";import{readFile as o,writeFile as r}from"node:fs/promises";const a={},e=t(n(),"i18next-cli-last-funnel-message-shown.json");async function s(t){if(a[t])return!1;try{const n=await o(e,"utf-8"),r=JSON.parse(n);if(Date.now()-(r[t]||0)<864e5)return!1}catch(t){}return!0}async function i(t){try{a[t]=!0;let n={};try{const t=await o(e,"utf-8");n=JSON.parse(t)}catch(t){}n[t]=Date.now(),await r(e,JSON.stringify(n))}catch(t){}}export{i as recordFunnelShown,s as shouldShowFunnel};
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readFile, writeFile } from 'node:fs/promises';
+
+/**
+ * In-memory cache to track which funnel messages have been shown in the current session.
+ */
+const hasLocizeFunnelBeenShown = {};
+/**
+ * Path to the persistent file that stores the last time each funnel message was shown.
+ * Stored in the OS temporary directory to persist across CLI sessions.
+ */
+const LAST_FUNNEL_FILE = join(tmpdir(), 'i18next-cli-last-funnel-message-shown.json'); // Store in OS temp dir
+/**
+ * Cooldown period in milliseconds before a funnel message can be shown again.
+ * Currently set to 24 hours.
+ */
+const TIP_COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 hours
+/**
+ * Determines whether a funnel message should be shown to the user.
+ *
+ * A funnel message will not be shown if:
+ * - It has already been shown in the current session (in-memory cache)
+ * - It was shown within the last 24 hours (persistent file cache)
+ *
+ * @param funnelMessage - The unique identifier for the funnel message
+ * @returns Promise that resolves to true if the message should be shown, false otherwise
+ */
+async function shouldShowFunnel(funnelMessage) {
+    if (hasLocizeFunnelBeenShown[funnelMessage])
+        return false;
+    try {
+        const content = await readFile(LAST_FUNNEL_FILE, 'utf-8');
+        const cnt = JSON.parse(content);
+        if (Date.now() - (cnt[funnelMessage] || 0) < TIP_COOLDOWN_MS) {
+            return false; // Less than 24 hours since last shown
+        }
+    }
+    catch (e) {
+        // File doesn't exist or is invalid, assume it's okay to show the tip
+    }
+    return true;
+}
+/**
+ * Records that a funnel message has been shown to the user.
+ *
+ * Updates both the in-memory cache and the persistent file cache with the current timestamp.
+ * This prevents the message from being shown again within the cooldown period.
+ *
+ * @param funnelMessage - The unique identifier for the funnel message that was shown
+ * @returns Promise that resolves when the record has been updated
+ */
+async function recordFunnelShown(funnelMessage) {
+    try {
+        hasLocizeFunnelBeenShown[funnelMessage] = true;
+        let data = {};
+        try {
+            const existing = await readFile(LAST_FUNNEL_FILE, 'utf-8');
+            data = JSON.parse(existing);
+        }
+        catch (err) {
+            // ignore, we'll create a new file
+        }
+        data[funnelMessage] = Date.now();
+        await writeFile(LAST_FUNNEL_FILE, JSON.stringify(data));
+    }
+    catch (e) {
+        // Ignore errors here, it's just a best-effort cache
+    }
+}
+
+export { recordFunnelShown, shouldShowFunnel };

package/dist/esm/utils/logger.js

@@ -1 +1,34 @@
-class o{info(o){console.log(o)}warn(o){console.warn(o)}error(o){console.error(o)}}export{o as ConsoleLogger};
+/**
+ * Default console-based logger implementation for the i18next toolkit.
+ * Provides basic logging functionality with different severity levels.
+ *
+ * @example
+ * ```typescript
+ * const logger = new ConsoleLogger()
+ * logger.info('Extraction started')
+ * logger.warn('Deprecated configuration option used')
+ * logger.error('Failed to parse file')
+ * ```
+ */
+class ConsoleLogger {
+    /**
+     * Logs an informational message to the console.
+     *
+     * @param message - The message to log
+     */
+    info(message) { console.log(message); }
+    /**
+     * Logs a warning message to the console.
+     *
+     * @param message - The warning message to log
+     */
+    warn(message) { console.warn(message); }
+    /**
+     * Logs an error message to the console.
+     *
+     * @param message - The error message to log
+     */
+    error(message) { console.error(message); }
+}
+
+export { ConsoleLogger };

package/dist/esm/utils/nested-object.js

@@ -1 +1,120 @@
-function t(t,e,n,r){if(!1===r)return void(t[e]=n);const o=e.split(r);let i=t;for(let r=0;r<o.length;r++){const u=o[r];if(r===o.length-1)return void(i[u]=n);const c=i[u];if(void 0!==c&&("object"!=typeof c||null===c))return void(t[e]=n);void 0===c&&(i[u]={}),i=i[u]}}function e(t,e,n){return!1===n?t[e]:e.split(n).reduce((t,e)=>t&&t[e],t)}function n(t,e,r=""){return!1===e?Object.keys(t):Object.entries(t).reduce((t,[o,i])=>{const u=r?`${r}${e}${o}`:o;return"object"!=typeof i||null===i||Array.isArray(i)?t.push(u):t.push(...n(i,e,u)),t},[])}export{n as getNestedKeys,e as getNestedValue,t as setNestedValue};
+/**
+ * Sets a nested value in an object using a key path and separator.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The target object to modify
+ * @param path - The key path (e.g., 'user.profile.name')
+ * @param value - The value to set
+ * @param keySeparator - The separator to use for splitting the path, or false for flat keys
+ *
+ * @example
+ * ```typescript
+ * const obj = {}
+ * setNestedValue(obj, 'user.profile.name', 'John', '.')
+ * // Result: { user: { profile: { name: 'John' } } }
+ *
+ * // With flat keys
+ * setNestedValue(obj, 'user.name', 'Jane', false)
+ * // Result: { 'user.name': 'Jane' }
+ * ```
+ */
+function setNestedValue(obj, path, value, keySeparator) {
+    if (keySeparator === false) {
+        obj[path] = value;
+        return;
+    }
+    const keys = path.split(keySeparator);
+    let current = obj;
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const isLastKey = i === keys.length - 1;
+        if (isLastKey) {
+            // We've reached the end of the path, set the value.
+            current[key] = value;
+            return;
+        }
+        const nextLevel = current[key];
+        // Check for a conflict: the path requires an object, but a primitive exists.
+        if (nextLevel !== undefined && (typeof nextLevel !== 'object' || nextLevel === null)) {
+            // Conflict detected. The parent path is already a leaf node.
+            // We must set the entire original path as a flat key on the root object.
+            obj[path] = value;
+            return; // Stop processing to prevent overwriting the parent.
+        }
+        // If the path doesn't exist, create an empty object to continue.
+        if (nextLevel === undefined) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+}
+/**
+ * Retrieves a nested value from an object using a key path and separator.
+ *
+ * @param obj - The object to search in
+ * @param path - The key path (e.g., 'user.profile.name')
+ * @param keySeparator - The separator to use for splitting the path, or false for flat keys
+ * @returns The found value or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const obj = { user: { profile: { name: 'John' } } }
+ * const name = getNestedValue(obj, 'user.profile.name', '.')
+ * // Returns: 'John'
+ *
+ * // With flat keys
+ * const flatObj = { 'user.name': 'Jane' }
+ * const name = getNestedValue(flatObj, 'user.name', false)
+ * // Returns: 'Jane'
+ * ```
+ */
+function getNestedValue(obj, path, keySeparator) {
+    if (keySeparator === false) {
+        return obj[path];
+    }
+    return path.split(keySeparator).reduce((acc, key) => acc && acc[key], obj);
+}
+/**
+ * Extracts all nested keys from an object, optionally with a prefix.
+ * Recursively traverses the object structure to build a flat list of key paths.
+ *
+ * @param obj - The object to extract keys from
+ * @param keySeparator - The separator to use for joining keys, or false for flat keys
+ * @param prefix - Optional prefix to prepend to all keys
+ * @returns Array of all nested key paths
+ *
+ * @example
+ * ```typescript
+ * const obj = {
+ *   user: {
+ *     profile: { name: 'John', age: 30 },
+ *     settings: { theme: 'dark' }
+ *   }
+ * }
+ *
+ * const keys = getNestedKeys(obj, '.')
+ * // Returns: ['user.profile.name', 'user.profile.age', 'user.settings.theme']
+ *
+ * // With flat keys
+ * const flatObj = { 'user.name': 'Jane', 'user.age': 25 }
+ * const flatKeys = getNestedKeys(flatObj, false)
+ * // Returns: ['user.name', 'user.age']
+ * ```
+ */
+function getNestedKeys(obj, keySeparator, prefix = '') {
+    if (keySeparator === false) {
+        return Object.keys(obj);
+    }
+    return Object.entries(obj).reduce((acc, [key, value]) => {
+        const newKey = prefix ? `${prefix}${keySeparator}${key}` : key;
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            acc.push(...getNestedKeys(value, keySeparator, newKey));
+        }
+        else {
+            acc.push(newKey);
+        }
+        return acc;
+    }, []);
+}
+
+export { getNestedKeys, getNestedValue, setNestedValue };

package/dist/esm/utils/validation.js

@@ -1 +1,68 @@
-function t(t){if(!t.extract.input?.length)throw new e("extract.input must be specified and non-empty");if(!t.extract.output)throw new e("extract.output must be specified");if(!t.locales?.length)throw new e("locales must be specified and non-empty");if("string"==typeof t.extract.output&&!t.extract.output.includes("{{language}}")&&!t.extract.output.includes("{{lng}}"))throw new e("extract.output must contain {{language}} placeholder")}class e extends Error{file;cause;constructor(t,e,n){super(e?`${t} in file ${e}`:t),this.file=e,this.cause=n,this.name="ExtractorError"}}export{e as ExtractorError,t as validateExtractorConfig};
+/**
+ * Validates the extractor configuration to ensure required fields are present and properly formatted.
+ *
+ * This function performs the following validations:
+ * - Ensures extract.input is specified and non-empty
+ * - Ensures extract.output is specified
+ * - Ensures locales array is specified and non-empty
+ * - Ensures extract.output contains the required {{language}} placeholder
+ *
+ * @param config - The i18next toolkit configuration object to validate
+ *
+ * @throws {ExtractorError} When any validation rule fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateExtractorConfig(config)
+ *   console.log('Configuration is valid')
+ * } catch (error) {
+ *   console.error('Invalid configuration:', error.message)
+ * }
+ * ```
+ */
+function validateExtractorConfig(config) {
+    if (!config.extract.input?.length) {
+        throw new ExtractorError('extract.input must be specified and non-empty');
+    }
+    if (!config.extract.output) {
+        throw new ExtractorError('extract.output must be specified');
+    }
+    if (!config.locales?.length) {
+        throw new ExtractorError('locales must be specified and non-empty');
+    }
+    // If output is a function, we accept it (user is responsible for producing a valid path).
+    if (typeof config.extract.output === 'string') {
+        if (!config.extract.output.includes('{{language}}') && !config.extract.output.includes('{{lng}}')) {
+            throw new ExtractorError('extract.output must contain {{language}} placeholder');
+        }
+    }
+}
+/**
+ * Custom error class for extraction-related errors.
+ * Provides additional context like file path and underlying cause.
+ *
+ * @example
+ * ```typescript
+ * throw new ExtractorError('Failed to parse file', 'src/component.tsx', syntaxError)
+ * ```
+ */
+class ExtractorError extends Error {
+    file;
+    cause;
+    /**
+     * Creates a new ExtractorError with optional file context and cause.
+     *
+     * @param message - The error message
+     * @param file - Optional file path where the error occurred
+     * @param cause - Optional underlying error that caused this error
+     */
+    constructor(message, file, cause) {
+        super(file ? `${message} in file ${file}` : message);
+        this.file = file;
+        this.cause = cause;
+        this.name = 'ExtractorError';
+    }
+}
+
+export { ExtractorError, validateExtractorConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next-cli",
-  "version": "1.34.0",
+  "version": "1.34.1",
   "description": "A unified, high-performance i18next CLI.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     }
   },
   "scripts": {
-    "build": "rm -rf dist && rollup -c && chmod +x dist/esm/cli.js && chmod +x dist/cjs/cli.js && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && rm -rf types && tsc -d --declarationDir types --declarationMap --emitDeclarationOnly",
+    "build": "rm -rf dist && rollup -c && rm -rf types && tsc -d --declarationDir types --declarationMap --emitDeclarationOnly",
     "lint": "eslint .",
     "test": "npm run lint && vitest run",
     "test:watch": "vitest",

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;AAiQnD,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;AAmQnD,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"}