i18next-cli 1.34.0 → 1.34.1

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

@@ -1 +1,406 @@
-import{getObjectPropValue as e}from"./ast-utils.js";class t{scopeStack=[];config;scope=new Map;simpleConstants=new Map;constructor(e){this.config=e}reset(){this.scopeStack=[],this.scope=new Map,this.simpleConstants.clear()}enterScope(){this.scopeStack.push(new Map)}exitScope(){this.scopeStack.pop()}setVarInScope(e,t){this.scopeStack.length>0?this.scopeStack[this.scopeStack.length-1].set(e,t):this.scope.set(e,t)}getVarFromScope(e){for(let t=this.scopeStack.length-1;t>=0;t--)if(this.scopeStack[t].has(e)){return this.scopeStack[t].get(e)}const t=this.scope.get(e);if(t)return t}getUseTranslationConfig(e){const t=this.config.extract.useTranslationNames||["useTranslation"];for(const i of t){if("string"==typeof i&&i===e)return{name:e,nsArg:0,keyPrefixArg:1};if("object"==typeof i&&i.name===e)return{name:i.name,nsArg:i.nsArg??0,keyPrefixArg:i.keyPrefixArg??1}}}resolveSimpleStringIdentifier(e){return this.simpleConstants.get(e)}handleVariableDeclarator(e){const t=e.init;if(!t)return;"Identifier"===e.id.type&&"StringLiteral"===t.type&&this.simpleConstants.set(e.id.value,t.value);const i="AwaitExpression"===t.type&&"CallExpression"===t.argument.type?t.argument:"CallExpression"===t.type?t:null;if(!i)return;const r=i.callee;if("Identifier"===r.type){const t=this.getUseTranslationConfig(r.value);if(t)return this.handleUseTranslationDeclarator(e,i,t),void this.handleUseTranslationForComments(e,i,t)}if("Identifier"===r.type){if(this.getVarFromScope(r.value))return void this.handleGetFixedTFromVariableDeclarator(e,i,r.value)}"MemberExpression"===r.type&&"Identifier"===r.property.type&&"getFixedT"===r.property.value&&this.handleGetFixedTDeclarator(e,i)}handleUseTranslationForComments(t,i,r){let s;if("Identifier"===t.id.type&&(s=t.id.value),"ArrayPattern"===t.id.type){const e=t.id.elements[0];"Identifier"===e?.type&&(s=e.value)}if("ObjectPattern"===t.id.type)for(const e of t.id.properties){if("AssignmentPatternProperty"===e.type&&"Identifier"===e.key.type&&("t"===e.key.value||"getFixedT"===e.key.value)){s=e.key.value;break}if("KeyValuePatternProperty"===e.type&&"Identifier"===e.key.type&&("t"===e.key.value||"getFixedT"===e.key.value)&&"Identifier"===e.value.type){s=e.value.value;break}}if(!s)return;const n=r.nsArg??0,a=r.keyPrefixArg??1;let o,l;const p=i.arguments?.[0]?.expression,y=i.arguments?.[1]?.expression,f=i.arguments?.[2]?.expression;var u;let c;if("useTranslation"===r.name&&"StringLiteral"===p?.type&&"StringLiteral"===y?.type&&(u=p.value,/^[a-z]{2,3}([-_][A-Za-z0-9-]+)?$/i.test(u)))o=y.value,c=f;else{if(-1!==n){const e=i.arguments?.[n]?.expression;"StringLiteral"===e?.type?o=e.value:"ArrayExpression"===e?.type&&"StringLiteral"===e.elements[0]?.expression?.type&&(o=e.elements[0].expression.value)}c=-1===a?void 0:i.arguments?.[a]?.expression}if("ObjectExpression"===c?.type){const t=e(c,"keyPrefix");l="string"==typeof t?t:void 0}else if("StringLiteral"===c?.type)l=c.value;else if("Identifier"===c?.type)l=this.resolveSimpleStringIdentifier(c.value);else if("TemplateLiteral"===c?.type){const e=c;0===(e.expressions||[]).length&&(l=e.quasis?.[0]?.cooked??void 0)}(o||l)&&this.scope.set(s,{defaultNs:o,keyPrefix:l})}handleUseTranslationDeclarator(t,i,r){let s;if("Identifier"===t.id.type&&(s=t.id.value),"ArrayPattern"===t.id.type){const e=t.id.elements[0];"Identifier"===e?.type&&(s=e.value)}if("ObjectPattern"===t.id.type)for(const e of t.id.properties){if("AssignmentPatternProperty"===e.type&&"Identifier"===e.key.type&&("t"===e.key.value||"getFixedT"===e.key.value)){s=e.key.value;break}if("KeyValuePatternProperty"===e.type&&"Identifier"===e.key.type&&("t"===e.key.value||"getFixedT"===e.key.value)&&"Identifier"===e.value.type){s=e.value.value;break}}if(!s)return;const n=r.nsArg??0,a=r.keyPrefixArg??1;let o,l;const p=i.arguments?.[0]?.expression,y=i.arguments?.[1]?.expression,f=i.arguments?.[2]?.expression;var u;let c;if("useTranslation"===r.name&&"StringLiteral"===p?.type&&"StringLiteral"===y?.type&&(u=p.value,/^[a-z]{2,3}([-_][A-Za-z0-9-]+)?$/i.test(u)))o=y.value,c=f;else{if(-1!==n){const e=i.arguments?.[n]?.expression;"StringLiteral"===e?.type?o=e.value:"ArrayExpression"===e?.type&&"StringLiteral"===e.elements[0]?.expression?.type&&(o=e.elements[0].expression.value)}c=-1===a?void 0:i.arguments?.[a]?.expression}if("ObjectExpression"===c?.type){const t=e(c,"keyPrefix");l="string"==typeof t?t:void 0}else if("StringLiteral"===c?.type)l=c.value;else if("Identifier"===c?.type)l=this.resolveSimpleStringIdentifier(c.value);else if("TemplateLiteral"===c?.type){const e=c;0===(e.expressions||[]).length&&(l=e.quasis?.[0]?.cooked??void 0)}this.setVarInScope(s,{defaultNs:o,keyPrefix:l})}handleGetFixedTDeclarator(e,t){if("Identifier"!==e.id.type||!e.init||"CallExpression"!==e.init.type)return;const i=e.id.value,r=t.arguments,s=r[1]?.expression,n=r[2]?.expression,a="StringLiteral"===s?.type?s.value:void 0,o="StringLiteral"===n?.type?n.value:void 0;(a||o)&&this.setVarInScope(i,{defaultNs:a,keyPrefix:o})}handleGetFixedTFromVariableDeclarator(e,t,i){if("Identifier"!==e.id.type)return;const r=e.id.value,s=this.getVarFromScope(i);if(!s)return;const n=t.arguments,a=n[1]?.expression,o=n[2]?.expression,l="StringLiteral"===a?.type?a.value:void 0,p="StringLiteral"===o?.type?o.value:void 0,y=l??s.defaultNs,f=p??s.keyPrefix;(y||f)&&this.setVarInScope(r,{defaultNs:y,keyPrefix:f})}}export{t as ScopeManager};
+import { getObjectPropValue } from './ast-utils.js';
+
+class ScopeManager {
+    scopeStack = [];
+    config;
+    scope = new Map();
+    // Track simple local constants with string literal values to resolve identifier args
+    simpleConstants = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Reset per-file scope state.
+     *
+     * This clears both the scope stack and the legacy scope map. It should be
+     * called at the start of processing each file so that scope info does not
+     * leak between files.
+     */
+    reset() {
+        this.scopeStack = [];
+        this.scope = new Map();
+        this.simpleConstants.clear();
+    }
+    /**
+     * Enters a new variable scope by pushing a new scope map onto the stack.
+     * Used when entering functions to isolate variable declarations.
+     */
+    enterScope() {
+        this.scopeStack.push(new Map());
+    }
+    /**
+     * Exits the current variable scope by popping the top scope map.
+     * Used when leaving functions to clean up variable tracking.
+     */
+    exitScope() {
+        this.scopeStack.pop();
+    }
+    /**
+     * Stores variable information in the current scope.
+     * Used to track translation functions and their configuration.
+     *
+     * @param name - Variable name to store
+     * @param info - Scope information about the variable
+     */
+    setVarInScope(name, info) {
+        if (this.scopeStack.length > 0) {
+            this.scopeStack[this.scopeStack.length - 1].set(name, info);
+        }
+        else {
+            // No active scope (top-level). Preserve in legacy scope map so lookups work
+            // for top-level variables (e.g., const { getFixedT } = useTranslate(...))
+            this.scope.set(name, info);
+        }
+    }
+    /**
+     * Retrieves variable information from the scope chain.
+     * Searches from innermost to outermost scope.
+     *
+     * @param name - Variable name to look up
+     * @returns Scope information if found, undefined otherwise
+     */
+    getVarFromScope(name) {
+        // First check the proper scope stack (this is the primary source of truth)
+        for (let i = this.scopeStack.length - 1; i >= 0; i--) {
+            if (this.scopeStack[i].has(name)) {
+                const scopeInfo = this.scopeStack[i].get(name);
+                return scopeInfo;
+            }
+        }
+        // Then check the legacy scope tracking for useTranslation calls (for comment parsing)
+        const legacyScope = this.scope.get(name);
+        if (legacyScope) {
+            return legacyScope;
+        }
+        return undefined;
+    }
+    getUseTranslationConfig(name) {
+        const useTranslationNames = this.config.extract.useTranslationNames || ['useTranslation'];
+        for (const item of useTranslationNames) {
+            if (typeof item === 'string' && item === name) {
+                // Default behavior for simple string entries
+                return { name, nsArg: 0, keyPrefixArg: 1 };
+            }
+            if (typeof item === 'object' && item.name === name) {
+                // Custom configuration with specified or default argument positions
+                return {
+                    name: item.name,
+                    nsArg: item.nsArg ?? 0,
+                    keyPrefixArg: item.keyPrefixArg ?? 1,
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve simple identifier declared in-file to its string literal value, if known.
+     */
+    resolveSimpleStringIdentifier(name) {
+        return this.simpleConstants.get(name);
+    }
+    /**
+     * Handles variable declarations that might define translation functions.
+     *
+     * Processes two patterns:
+     * 1. `const { t } = useTranslation(...)` - React i18next pattern
+     * 2. `const t = i18next.getFixedT(...)` - Core i18next pattern
+     *
+     * Extracts namespace and key prefix information for later use.
+     *
+     * @param node - Variable declarator node to process
+     */
+    handleVariableDeclarator(node) {
+        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);
+            // continue processing; still may be a useTranslation/getFixedT call below
+        }
+        // Determine the actual call expression, looking inside AwaitExpressions.
+        const callExpr = init.type === 'AwaitExpression' && init.argument.type === 'CallExpression'
+            ? init.argument
+            : init.type === 'CallExpression'
+                ? init
+                : null;
+        if (!callExpr)
+            return;
+        const callee = callExpr.callee;
+        // Handle: const { t } = useTranslation(...)
+        if (callee.type === 'Identifier') {
+            const hookConfig = this.getUseTranslationConfig(callee.value);
+            if (hookConfig) {
+                this.handleUseTranslationDeclarator(node, callExpr, hookConfig);
+                // ALSO store in the legacy scope for comment parsing compatibility
+                this.handleUseTranslationForComments(node, callExpr, hookConfig);
+                return;
+            }
+        }
+        // Handle: const t = getFixedT(...) where getFixedT is a previously declared variable
+        // (e.g., `const { getFixedT } = useTranslate('helloservice')`)
+        if (callee.type === 'Identifier') {
+            const sourceScope = this.getVarFromScope(callee.value);
+            if (sourceScope) {
+                // Propagate the source scope (keyPrefix/defaultNs) and augment it with
+                // arguments passed to this call (e.g., namespace argument).
+                this.handleGetFixedTFromVariableDeclarator(node, callExpr, callee.value);
+                return;
+            }
+        }
+        // Handle: const t = i18next.getFixedT(...)
+        if (callee.type === 'MemberExpression' &&
+            callee.property.type === 'Identifier' &&
+            callee.property.value === 'getFixedT') {
+            this.handleGetFixedTDeclarator(node, callExpr);
+        }
+    }
+    /**
+     * Handles useTranslation calls for comment scope resolution.
+     * This is a separate method to store scope info in the legacy scope map
+     * that the comment parser can access.
+     *
+     * @param node - Variable declarator with useTranslation call
+     * @param callExpr - The CallExpression node representing the useTranslation invocation
+     * @param hookConfig - Configuration describing argument positions for namespace and keyPrefix
+     */
+    handleUseTranslationForComments(node, callExpr, hookConfig) {
+        let variableName;
+        // Handle simple assignment: let t = useTranslation()
+        if (node.id.type === 'Identifier') {
+            variableName = node.id.value;
+        }
+        // Handle array destructuring: const [t, i18n] = useTranslation()
+        if (node.id.type === 'ArrayPattern') {
+            const firstElement = node.id.elements[0];
+            if (firstElement?.type === 'Identifier') {
+                variableName = firstElement.value;
+            }
+        }
+        // Handle object destructuring: const { t } or { t: t1 } = useTranslation()
+        if (node.id.type === 'ObjectPattern') {
+            for (const prop of node.id.properties) {
+                // Support both 't' and 'getFixedT' (and preserve existing behavior for 't').
+                if (prop.type === 'AssignmentPatternProperty' && prop.key.type === 'Identifier' && (prop.key.value === 't' || prop.key.value === 'getFixedT')) {
+                    variableName = prop.key.value;
+                    break;
+                }
+                if (prop.type === 'KeyValuePatternProperty' && prop.key.type === 'Identifier' && (prop.key.value === 't' || prop.key.value === 'getFixedT') && prop.value.type === 'Identifier') {
+                    variableName = prop.value.value;
+                    break;
+                }
+            }
+        }
+        // If we couldn't find a `t` function being declared, exit
+        if (!variableName)
+            return;
+        // Position-driven extraction: respect hookConfig positions (nsArg/keyPrefixArg).
+        // nsArg === -1 means "no namespace arg"; keyPrefixArg === -1 means "no keyPrefix arg".
+        const nsArgIndex = hookConfig.nsArg ?? 0;
+        const kpArgIndex = hookConfig.keyPrefixArg ?? 1;
+        let defaultNs;
+        let keyPrefix;
+        // Early detection of react-i18next common form: useTranslation(lng, ns)
+        // Only apply for the built-in hook name to avoid interfering with custom hooks.
+        const first = callExpr.arguments?.[0]?.expression;
+        const second = callExpr.arguments?.[1]?.expression;
+        const third = callExpr.arguments?.[2]?.expression;
+        const looksLikeLanguage = (s) => /^[a-z]{2,3}([-_][A-Za-z0-9-]+)?$/i.test(s);
+        const isBuiltInLngNsForm = hookConfig.name === 'useTranslation' &&
+            first?.type === 'StringLiteral' &&
+            second?.type === 'StringLiteral' &&
+            looksLikeLanguage(first.value);
+        let kpArg;
+        if (isBuiltInLngNsForm) {
+            // treat as useTranslation(lng, ns, [options])
+            defaultNs = second.value;
+            // prefer third arg as keyPrefix (may be undefined)
+            kpArg = third;
+        }
+        else {
+            // Position-driven extraction: respect hookConfig positions (nsArg/keyPrefixArg).
+            if (nsArgIndex !== -1) {
+                const nsNode = callExpr.arguments?.[nsArgIndex]?.expression;
+                if (nsNode?.type === 'StringLiteral') {
+                    defaultNs = nsNode.value;
+                }
+                else if (nsNode?.type === 'ArrayExpression' && nsNode.elements[0]?.expression?.type === 'StringLiteral') {
+                    defaultNs = nsNode.elements[0].expression.value;
+                }
+            }
+            kpArg = kpArgIndex === -1 ? undefined : callExpr.arguments?.[kpArgIndex]?.expression;
+        }
+        if (kpArg?.type === 'ObjectExpression') {
+            const kp = getObjectPropValue(kpArg, 'keyPrefix');
+            keyPrefix = typeof kp === 'string' ? kp : undefined;
+        }
+        else if (kpArg?.type === 'StringLiteral') {
+            keyPrefix = kpArg.value;
+        }
+        else if (kpArg?.type === 'Identifier') {
+            keyPrefix = this.resolveSimpleStringIdentifier(kpArg.value);
+        }
+        else if (kpArg?.type === 'TemplateLiteral') {
+            const tpl = kpArg;
+            if ((tpl.expressions || []).length === 0) {
+                keyPrefix = tpl.quasis?.[0]?.cooked ?? undefined;
+            }
+        }
+        // Store in the legacy scope map for comment parsing
+        if (defaultNs || keyPrefix) {
+            this.scope.set(variableName, { defaultNs, keyPrefix });
+        }
+    }
+    /**
+     * Processes useTranslation hook declarations to extract scope information.
+     *
+     * Handles various destructuring patterns:
+     * - `const [t] = useTranslation('ns')` - Array destructuring
+     * - `const { t } = useTranslation('ns')` - Object destructuring
+     * - `const { t: myT } = useTranslation('ns')` - Aliased destructuring
+     *
+     * Extracts namespace from the first argument and keyPrefix from options.
+     *
+     * @param node - Variable declarator with useTranslation call
+     * @param callExpr - The CallExpression node representing the useTranslation invocation
+     * @param hookConfig - Configuration describing argument positions for namespace and keyPrefix
+     */
+    handleUseTranslationDeclarator(node, callExpr, hookConfig) {
+        let variableName;
+        // Handle simple assignment: let t = useTranslation()
+        if (node.id.type === 'Identifier') {
+            variableName = node.id.value;
+        }
+        // Handle array destructuring: const [t, i18n] = useTranslation()
+        if (node.id.type === 'ArrayPattern') {
+            const firstElement = node.id.elements[0];
+            if (firstElement?.type === 'Identifier') {
+                variableName = firstElement.value;
+            }
+        }
+        // Handle object destructuring: const { t } or { t: t1 } = useTranslation()
+        if (node.id.type === 'ObjectPattern') {
+            for (const prop of node.id.properties) {
+                // Also consider getFixedT so scope info is attached to that identifier
+                if (prop.type === 'AssignmentPatternProperty' && prop.key.type === 'Identifier' && (prop.key.value === 't' || prop.key.value === 'getFixedT')) {
+                    variableName = prop.key.value;
+                    break;
+                }
+                if (prop.type === 'KeyValuePatternProperty' && prop.key.type === 'Identifier' && (prop.key.value === 't' || prop.key.value === 'getFixedT') && prop.value.type === 'Identifier') {
+                    variableName = prop.value.value;
+                    break;
+                }
+            }
+        }
+        // If we couldn't find a `t` function being declared, exit
+        if (!variableName)
+            return;
+        // Position-driven extraction: respect hookConfig positions (nsArg/keyPrefixArg).
+        const nsArgIndex = hookConfig.nsArg ?? 0;
+        const kpArgIndex = hookConfig.keyPrefixArg ?? 1;
+        let defaultNs;
+        let keyPrefix;
+        // Early detect useTranslation(lng, ns) for built-in hook name only
+        const first = callExpr.arguments?.[0]?.expression;
+        const second = callExpr.arguments?.[1]?.expression;
+        const third = callExpr.arguments?.[2]?.expression;
+        const looksLikeLanguage = (s) => /^[a-z]{2,3}([-_][A-Za-z0-9-]+)?$/i.test(s);
+        const isBuiltInLngNsForm = hookConfig.name === 'useTranslation' &&
+            first?.type === 'StringLiteral' &&
+            second?.type === 'StringLiteral' &&
+            looksLikeLanguage(first.value);
+        let kpArg;
+        if (isBuiltInLngNsForm) {
+            defaultNs = second.value;
+            kpArg = third;
+        }
+        else {
+            if (nsArgIndex !== -1) {
+                const nsNode = callExpr.arguments?.[nsArgIndex]?.expression;
+                if (nsNode?.type === 'StringLiteral')
+                    defaultNs = nsNode.value;
+                else if (nsNode?.type === 'ArrayExpression' && nsNode.elements[0]?.expression?.type === 'StringLiteral') {
+                    defaultNs = nsNode.elements[0].expression.value;
+                }
+            }
+            kpArg = kpArgIndex === -1 ? undefined : callExpr.arguments?.[kpArgIndex]?.expression;
+        }
+        if (kpArg?.type === 'ObjectExpression') {
+            const kp = getObjectPropValue(kpArg, 'keyPrefix');
+            keyPrefix = typeof kp === 'string' ? kp : undefined;
+        }
+        else if (kpArg?.type === 'StringLiteral') {
+            keyPrefix = kpArg.value;
+        }
+        else if (kpArg?.type === 'Identifier') {
+            keyPrefix = this.resolveSimpleStringIdentifier(kpArg.value);
+        }
+        else if (kpArg?.type === 'TemplateLiteral') {
+            const tpl = kpArg;
+            if ((tpl.expressions || []).length === 0) {
+                keyPrefix = tpl.quasis?.[0]?.cooked ?? undefined;
+            }
+        }
+        // Store the scope info for the declared variable
+        this.setVarInScope(variableName, { defaultNs, keyPrefix });
+    }
+    /**
+     * Processes getFixedT function declarations to extract scope information.
+     *
+     * Handles the pattern: `const t = i18next.getFixedT(lng, ns, keyPrefix)`
+     * - Ignores the first argument (language)
+     * - Extracts namespace from the second argument
+     * - Extracts key prefix from the third argument
+     *
+     * @param node - Variable declarator with getFixedT call
+     * @param callExpr - The CallExpression node representing the getFixedT invocation
+     */
+    handleGetFixedTDeclarator(node, callExpr) {
+        // Ensure we are assigning to a simple variable, e.g., const t = ...
+        if (node.id.type !== 'Identifier' || !node.init || node.init.type !== 'CallExpression')
+            return;
+        const variableName = node.id.value;
+        const args = callExpr.arguments;
+        // getFixedT(lng, ns, keyPrefix)
+        // We ignore the first argument (lng) for key extraction.
+        const nsArg = args[1]?.expression;
+        const keyPrefixArg = args[2]?.expression;
+        const defaultNs = (nsArg?.type === 'StringLiteral') ? nsArg.value : undefined;
+        const keyPrefix = (keyPrefixArg?.type === 'StringLiteral') ? keyPrefixArg.value : undefined;
+        if (defaultNs || keyPrefix) {
+            this.setVarInScope(variableName, { defaultNs, keyPrefix });
+        }
+    }
+    /**
+     * Handles cases where a getFixedT-like function is a variable (from a custom hook)
+     * and is invoked to produce a bound `t` function, e.g.:
+     *   const { getFixedT } = useTranslate('prefix')
+     *   const t = getFixedT('en', 'ns')
+     *
+     * We combine the original source variable's scope (keyPrefix/defaultNs) with
+     * any namespace/keyPrefix arguments provided to this call and attach the
+     * resulting scope to the newly declared variable.
+     */
+    handleGetFixedTFromVariableDeclarator(node, callExpr, sourceVarName) {
+        if (node.id.type !== 'Identifier')
+            return;
+        const targetVarName = node.id.value;
+        const sourceScope = this.getVarFromScope(sourceVarName);
+        if (!sourceScope)
+            return;
+        const args = callExpr.arguments;
+        // getFixedT(lng, ns, keyPrefix)
+        const nsArg = args[1]?.expression;
+        const keyPrefixArg = args[2]?.expression;
+        const nsFromCall = (nsArg?.type === 'StringLiteral') ? nsArg.value : undefined;
+        const keyPrefixFromCall = (keyPrefixArg?.type === 'StringLiteral') ? keyPrefixArg.value : undefined;
+        // Merge: call args take precedence over source scope values
+        const finalNs = nsFromCall ?? sourceScope.defaultNs;
+        const finalKeyPrefix = keyPrefixFromCall ?? sourceScope.keyPrefix;
+        if (finalNs || finalKeyPrefix) {
+            this.setVarInScope(targetVarName, { defaultNs: finalNs, keyPrefix: finalKeyPrefix });
+        }
+    }
+}
+
+export { ScopeManager };

package/dist/esm/extractor/plugin-manager.js

@@ -1 +1,103 @@
-async function t(t){for(const e of t)await(e.setup?.())}function e(t,e,a,n){return{addKey:e=>{const n=!1===e.ns?void 0:e.ns,l=n??a.extract?.defaultNS??"translation",o=void 0===n,s=`${String(l)}:${e.key}`,i=e.defaultValue??e.key,u=t.get(s);if(u){const n=u.defaultValue===u.key||u.hasCount&&u.defaultValue&&u.key.includes("_")&&u.key.startsWith(u.defaultValue),c=i===e.key;e.locations&&(u.locations=[...u.locations||[],...e.locations]),n&&!c&&t.set(s,{...e,ns:l||a.extract?.defaultNS||"translation",nsIsImplicit:o,defaultValue:i,locations:u.locations})}else t.set(s,{...e,ns:l||a.extract?.defaultNS||"translation",nsIsImplicit:o,defaultValue:i})},config:Object.freeze({...a,plugins:[...e]}),logger:n,getVarFromScope:()=>{}}}export{e as createPluginContext,t as initializePlugins};
+/**
+ * Initializes an array of plugins by calling their setup hooks.
+ * This function should be called before starting the extraction process.
+ *
+ * @param plugins - Array of plugin objects to initialize
+ *
+ * @example
+ * ```typescript
+ * const plugins = [customPlugin(), anotherPlugin()]
+ * await initializePlugins(plugins)
+ * // All plugin setup hooks have been called
+ * ```
+ */
+async function initializePlugins(plugins) {
+    for (const plugin of plugins) {
+        await plugin.setup?.();
+    }
+}
+/**
+ * Creates a plugin context object that provides helper methods for plugins.
+ * The context allows plugins to add extracted keys to the main collection.
+ *
+ * @param allKeys - The main map where extracted keys are stored
+ * @returns A context object with helper methods for plugins
+ *
+ * @example
+ * ```typescript
+ * const allKeys = new Map()
+ * const context = createPluginContext(allKeys)
+ *
+ * // Plugin can now add keys
+ * context.addKey({
+ *   key: 'my.custom.key',
+ *   defaultValue: 'Default Value',
+ *   ns: 'common'
+ * })
+ * ```
+ */
+function createPluginContext(allKeys, plugins, config, logger) {
+    const pluginContextConfig = Object.freeze({
+        ...config,
+        plugins: [...plugins],
+    });
+    return {
+        addKey: (keyInfo) => {
+            // Normalize boolean `false` namespace -> undefined (meaning "no explicit ns")
+            const explicitNs = keyInfo.ns === false ? undefined : keyInfo.ns;
+            // Internally prefer 'translation' as the logical namespace when none was specified.
+            // Record whether the namespace was implicit so the output generator can
+            // special-case config.extract.defaultNS === false.
+            const storedNs = explicitNs ?? (config.extract?.defaultNS ?? 'translation');
+            const nsIsImplicit = explicitNs === undefined;
+            const nsForKey = String(storedNs);
+            const uniqueKey = `${nsForKey}:${keyInfo.key}`;
+            const defaultValue = keyInfo.defaultValue ?? keyInfo.key;
+            // Check if key already exists
+            const existingKey = allKeys.get(uniqueKey);
+            if (existingKey) {
+                // Check if existing value is a generic fallback
+                // For plural keys, the fallback is often the base key (e.g., "item.count" for "item.count_other")
+                // For regular keys, the fallback is the key itself
+                const isExistingGenericFallback = existingKey.defaultValue === existingKey.key || // Regular key fallback
+                    (existingKey.hasCount && existingKey.defaultValue &&
+                        existingKey.key.includes('_') &&
+                        existingKey.key.startsWith(existingKey.defaultValue)); // Plural key with base key fallback
+                const isNewGenericFallback = defaultValue === keyInfo.key;
+                // Merge locations
+                if (keyInfo.locations) {
+                    existingKey.locations = [
+                        ...(existingKey.locations || []),
+                        ...keyInfo.locations
+                    ];
+                }
+                // If existing value is a generic fallback and new value is specific, replace it
+                if (isExistingGenericFallback && !isNewGenericFallback) {
+                    allKeys.set(uniqueKey, {
+                        ...keyInfo,
+                        ns: storedNs || config.extract?.defaultNS || 'translation',
+                        nsIsImplicit,
+                        defaultValue,
+                        locations: existingKey.locations // Preserve merged locations
+                    });
+                }
+                // Otherwise keep the existing one
+            }
+            else {
+                // New key, just add it
+                allKeys.set(uniqueKey, {
+                    ...keyInfo,
+                    ns: storedNs || config.extract?.defaultNS || 'translation',
+                    nsIsImplicit,
+                    defaultValue
+                });
+            }
+        },
+        config: pluginContextConfig,
+        logger,
+        // This will be attached later, so we provide a placeholder
+        getVarFromScope: () => undefined,
+    };
+}
+
+export { createPluginContext, initializePlugins };

package/dist/esm/heuristic-config.js

@@ -1 +1,97 @@
-import{glob as s}from"glob";import{readdir as e}from"node:fs/promises";import{extname as n,dirname as o,join as l}from"node:path";const c=["public/locales/dev/*.json","locales/dev/*.json","src/locales/dev/*.json","src/assets/locales/dev/*.json","app/i18n/locales/dev/*.json","src/i18n/locales/dev/*.json","public/locales/en/*.json","locales/en/*.json","src/locales/en/*.json","src/assets/locales/en/*.json","app/i18n/locales/en/*.json","src/i18n/locales/en/*.json","public/locales/en/*.json5","locales/en/*.json5","src/locales/en/*.json5","src/assets/locales/en/*.json5","app/i18n/locales/en/*.json5","src/i18n/locales/en/*.json5","public/locales/en-*/*.json","locales/en-*/*.json","src/locales/en-*/*.json","src/assets/locales/en-*/*.json","app/i18n/locales/en-*/*.json","src/i18n/locales/en-*/*.json"];async function a(){for(const a of c){const c=await s(a,{ignore:"node_modules/**"});if(c.length>0){const s=c.find(s=>".json5"===n(s))||c[0],a=o(o(s)),t=n(s);let j="json";".ts"===t?j="ts":".js"===t?j="js":".json5"===t&&(j="json5");try{let s=(await e(a)).filter(s=>/^(dev|[a-z]{2}(-[A-Z]{2})?)$/.test(s));if(s.length>0)return s.sort(),s.includes("dev")&&(s=["dev",...s.filter(s=>"dev"!==s)]),s.includes("en")&&(s=["en",...s.filter(s=>"en"!==s)]),{locales:s,extract:{input:["src/**/*.{js,jsx,ts,tsx}","app/**/*.{js,jsx,ts,tsx}","pages/**/*.{js,jsx,ts,tsx}","components/**/*.{js,jsx,ts,tsx}"],output:l(a,"{{language}}",`{{namespace}}${t}`),outputFormat:j,primaryLanguage:s.includes("en")?"en":s[0]}}}catch{continue}}}return null}export{a as detectConfig};
+import { glob } from 'glob';
+import { readdir } from 'node:fs/promises';
+import { extname, dirname, join } from 'node:path';
+
+// A list of common glob patterns for the primary language ('en') or ('dev') translation files.
+const HEURISTIC_PATTERNS = [
+    'public/locales/dev/*.json',
+    'locales/dev/*.json',
+    'src/locales/dev/*.json',
+    'src/assets/locales/dev/*.json',
+    'app/i18n/locales/dev/*.json',
+    'src/i18n/locales/dev/*.json',
+    'public/locales/en/*.json',
+    'locales/en/*.json',
+    'src/locales/en/*.json',
+    'src/assets/locales/en/*.json',
+    'app/i18n/locales/en/*.json',
+    'src/i18n/locales/en/*.json',
+    'public/locales/en/*.json5',
+    'locales/en/*.json5',
+    'src/locales/en/*.json5',
+    'src/assets/locales/en/*.json5',
+    'app/i18n/locales/en/*.json5',
+    'src/i18n/locales/en/*.json5',
+    'public/locales/en-*/*.json',
+    'locales/en-*/*.json',
+    'src/locales/en-*/*.json',
+    'src/assets/locales/en-*/*.json',
+    'app/i18n/locales/en-*/*.json',
+    'src/i18n/locales/en-*/*.json',
+];
+/**
+ * Attempts to automatically detect the project's i18n structure by searching for
+ * common translation file locations.
+ *
+ * @returns A promise that resolves to a partial I18nextToolkitConfig if detection
+ * is successful, otherwise null.
+ */
+async function detectConfig() {
+    for (const pattern of HEURISTIC_PATTERNS) {
+        const files = await glob(pattern, { ignore: 'node_modules/**' });
+        if (files.length > 0) {
+            // Prefer .json5 if present
+            const json5File = files.find(f => extname(f) === '.json5');
+            const firstFile = json5File || files[0];
+            const basePath = dirname(dirname(firstFile));
+            const extension = extname(firstFile);
+            // Infer outputFormat from the file extension
+            let outputFormat = 'json';
+            if (extension === '.ts') {
+                outputFormat = 'ts';
+            }
+            else if (extension === '.js') {
+                // We can't know if it's ESM or CJS, so we default to a safe choice.
+                // The tool's file loaders can handle both.
+                outputFormat = 'js';
+            }
+            else if (extension === '.json5') {
+                outputFormat = 'json5';
+            }
+            try {
+                const allDirs = await readdir(basePath);
+                let locales = allDirs.filter(dir => /^(dev|[a-z]{2}(-[A-Z]{2})?)$/.test(dir));
+                if (locales.length > 0) {
+                    // Prioritization Logic
+                    locales.sort();
+                    if (locales.includes('dev')) {
+                        locales = ['dev', ...locales.filter(l => l !== 'dev')];
+                    }
+                    if (locales.includes('en')) {
+                        locales = ['en', ...locales.filter(l => l !== 'en')];
+                    }
+                    return {
+                        locales,
+                        extract: {
+                            input: [
+                                'src/**/*.{js,jsx,ts,tsx}',
+                                'app/**/*.{js,jsx,ts,tsx}',
+                                'pages/**/*.{js,jsx,ts,tsx}',
+                                'components/**/*.{js,jsx,ts,tsx}'
+                            ],
+                            output: join(basePath, '{{language}}', `{{namespace}}${extension}`),
+                            outputFormat,
+                            primaryLanguage: locales.includes('en') ? 'en' : locales[0],
+                        },
+                    };
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+
+export { detectConfig };

package/dist/esm/index.js

@@ -1 +1,11 @@
-export{defineConfig}from"./config.js";export{extract,runExtractor}from"./extractor/core/extractor.js";export{findKeys}from"./extractor/core/key-finder.js";export{getTranslations}from"./extractor/core/translation-manager.js";import"react";import"react-i18next";export{recommendedAcceptedAttributes,recommendedAcceptedTags,runLinter}from"./linter.js";export{runSyncer}from"./syncer.js";export{runStatus}from"./status.js";export{runTypesGenerator}from"./types-generator.js";export{runRenameKey}from"./rename-key.js";
+export { defineConfig } from './config.js';
+export { extract, runExtractor } from './extractor/core/extractor.js';
+export { findKeys } from './extractor/core/key-finder.js';
+export { getTranslations } from './extractor/core/translation-manager.js';
+import 'react';
+import 'react-i18next';
+export { recommendedAcceptedAttributes, recommendedAcceptedTags, runLinter } from './linter.js';
+export { runSyncer } from './syncer.js';
+export { runStatus } from './status.js';
+export { runTypesGenerator } from './types-generator.js';
+export { runRenameKey } from './rename-key.js';