i18next-cli 1.34.0 → 1.35.0

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

@@ -1 +1,43 @@
-"use strict";exports.resolveDefaultValue=function(t,e,r,u,n){if("function"==typeof t)try{return t(e,r,u,n||e)}catch(t){return""}return t||""};
+'use strict';
+
+/**
+ * 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 || '';
+}
+
+exports.resolveDefaultValue = resolveDefaultValue;

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

@@ -1 +1,136 @@
-"use strict";var e=require("node:fs/promises"),t=require("node:path"),r=require("jiti"),n=require("../config.js"),s=require("@croct/json5-parser");exports.getOutputPath=function(e,r,n){if(!e)return t.normalize(`locales/${r}/${n??"translation"}.json`);if("function"==typeof e)try{const s=String(e(r,n));return t.normalize(s.replace(/\/\/+/g,"/"))}catch{return t.normalize(`locales/${r}/${n??"translation"}.json`)}let s=String(e);return s=s.replace(/\{\{language\}\}|\{\{lng\}\}/g,r),s=null!=n?s.replace(/\{\{namespace\}\}/g,n):s.replace(/\/?\{\{namespace\}\}/g,""),s=s.replace(/\/\/+/g,"/"),t.normalize(s)},exports.loadRawJson5Content=async function(r){const n=t.resolve(process.cwd(),r);try{return await e.access(n),await e.readFile(n,"utf-8")}catch{return null}},exports.loadTranslationFile=async function(a){const o=t.resolve(process.cwd(),a);try{await e.access(o)}catch{return null}try{const a=t.extname(o).toLowerCase();if(".json5"===a){const t=await e.readFile(o,"utf-8");return s.JsonParser.parse(t,s.JsonObjectNode).toJSON()}if(".json"===a){const t=await e.readFile(o,"utf-8");return JSON.parse(t)}if(".ts"===a||".js"===a){const e=await n.getTsConfigAliases(),t=r.createJiti(process.cwd(),{alias:e,interopDefault:!0});return await t.import(o,{default:!0})}return null}catch(e){return console.warn(`Could not parse translation file ${a}:`,e),null}},exports.serializeTranslationFile=function(e,t="json",r=2,n){const a=JSON.stringify(e,null,r);switch(t){case"json5":if(n){const t=s.JsonParser.parse(n,s.JsonObjectNode);return t.update(e),t.toString({object:{indentationSize:Number(r)??2}})}return s.JsonParser.parse(a,s.JsonObjectNode).toString({object:{indentationSize:Number(r)??2}});case"js":case"js-esm":return`export default ${a};\n`;case"js-cjs":return`module.exports = ${a};\n`;case"ts":return`export default ${a} as const;\n`;default:return`${a}\n`}};
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+var jiti = require('jiti');
+var config = require('../config.js');
+var json5Parser = require('@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 node_path.normalize(`locales/${language}/${namespace ?? 'translation'}.json`);
+    }
+    if (typeof outputTemplate === 'function') {
+        try {
+            const result = String(outputTemplate(language, namespace));
+            return node_path.normalize(result.replace(/\/\/+/g, '/'));
+        }
+        catch {
+            // If user function throws, fallback to default path
+            return node_path.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 node_path.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 = node_path.resolve(process.cwd(), filePath);
+    try {
+        await promises.access(fullPath);
+    }
+    catch {
+        return null; // File doesn't exist
+    }
+    try {
+        const ext = node_path.extname(fullPath).toLowerCase();
+        if (ext === '.json5') {
+            const content = await promises.readFile(fullPath, 'utf-8');
+            // Parse as a JSON5 object node
+            const node = json5Parser.JsonParser.parse(content, json5Parser.JsonObjectNode);
+            return node.toJSON();
+        }
+        else if (ext === '.json') {
+            const content = await promises.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 config.getTsConfigAliases();
+            const jiti$1 = jiti.createJiti(process.cwd(), {
+                alias: aliases,
+                interopDefault: true,
+            });
+            const module = await jiti$1.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 = node_path.resolve(process.cwd(), filePath);
+    try {
+        await promises.access(fullPath);
+        return await promises.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 = json5Parser.JsonParser.parse(rawContent, json5Parser.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 = json5Parser.JsonParser.parse(jsonString, json5Parser.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`;
+    }
+}
+
+exports.getOutputPath = getOutputPath;
+exports.loadRawJson5Content = loadRawJson5Content;
+exports.loadTranslationFile = loadTranslationFile;
+exports.serializeTranslationFile = serializeTranslationFile;

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

@@ -1 +1,75 @@
-"use strict";var e=require("node:path"),t=require("node:os"),n=require("node:fs/promises");const r={},i=e.join(t.tmpdir(),"i18next-cli-last-funnel-message-shown.json");exports.recordFunnelShown=async function(e){try{r[e]=!0;let t={};try{const e=await n.readFile(i,"utf-8");t=JSON.parse(e)}catch(e){}t[e]=Date.now(),await n.writeFile(i,JSON.stringify(t))}catch(e){}},exports.shouldShowFunnel=async function(e){if(r[e])return!1;try{const t=await n.readFile(i,"utf-8"),r=JSON.parse(t);if(Date.now()-(r[e]||0)<864e5)return!1}catch(e){}return!0};
+'use strict';
+
+var node_path = require('node:path');
+var node_os = require('node:os');
+var promises = require('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 = node_path.join(node_os.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 promises.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 promises.readFile(LAST_FUNNEL_FILE, 'utf-8');
+            data = JSON.parse(existing);
+        }
+        catch (err) {
+            // ignore, we'll create a new file
+        }
+        data[funnelMessage] = Date.now();
+        await promises.writeFile(LAST_FUNNEL_FILE, JSON.stringify(data));
+    }
+    catch (e) {
+        // Ignore errors here, it's just a best-effort cache
+    }
+}
+
+exports.recordFunnelShown = recordFunnelShown;
+exports.shouldShowFunnel = shouldShowFunnel;

package/dist/cjs/utils/logger.js

@@ -1 +1,36 @@
-"use strict";exports.ConsoleLogger=class{info(o){console.log(o)}warn(o){console.warn(o)}error(o){console.error(o)}};
+'use strict';
+
+/**
+ * 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); }
+}
+
+exports.ConsoleLogger = ConsoleLogger;

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

@@ -1 +1,124 @@
-"use strict";exports.getNestedKeys=function e(t,r,n=""){return!1===r?Object.keys(t):Object.entries(t).reduce((t,[s,o])=>{const u=n?`${n}${r}${s}`:s;return"object"!=typeof o||null===o||Array.isArray(o)?t.push(u):t.push(...e(o,r,u)),t},[])},exports.getNestedValue=function(e,t,r){return!1===r?e[t]:t.split(r).reduce((e,t)=>e&&e[t],e)},exports.setNestedValue=function(e,t,r,n){if(!1===n)return void(e[t]=r);const s=t.split(n);let o=e;for(let n=0;n<s.length;n++){const u=s[n];if(n===s.length-1)return void(o[u]=r);const i=o[u];if(void 0!==i&&("object"!=typeof i||null===i))return void(e[t]=r);void 0===i&&(o[u]={}),o=o[u]}};
+'use strict';
+
+/**
+ * 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;
+    }, []);
+}
+
+exports.getNestedKeys = getNestedKeys;
+exports.getNestedValue = getNestedValue;
+exports.setNestedValue = setNestedValue;

package/dist/cjs/utils/validation.js

@@ -1 +1,71 @@
-"use strict";class t extends Error{file;cause;constructor(t,e,r){super(e?`${t} in file ${e}`:t),this.file=e,this.cause=r,this.name="ExtractorError"}}exports.ExtractorError=t,exports.validateExtractorConfig=function(e){if(!e.extract.input?.length)throw new t("extract.input must be specified and non-empty");if(!e.extract.output)throw new t("extract.output must be specified");if(!e.locales?.length)throw new t("locales must be specified and non-empty");if("string"==typeof e.extract.output&&!e.extract.output.includes("{{language}}")&&!e.extract.output.includes("{{lng}}"))throw new t("extract.output must contain {{language}} placeholder")};
+'use strict';
+
+/**
+ * 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';
+    }
+}
+
+exports.ExtractorError = ExtractorError;
+exports.validateExtractorConfig = validateExtractorConfig;