i18next-cli 1.47.6 → 1.47.8

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.6'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.8'); // 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/instrumenter/core/instrumenter.js

@@ -454,12 +454,41 @@ function addComponentFromFunctionNode(name, fnNode, content, components) {
 // Non-translatable JSX attributes are defined in utils/jsx-attributes.ts
 // and shared with the linter. The instrumenter uses `ignoredAttributeSet`
 // to skip recursing into non-translatable attribute values.
+/**
+ * Returns true when the AST node is a `t(...)` or `i18next.t(...)` call
+ * expression — i.e. code that was already instrumented.
+ */
+function isTranslationCall(node) {
+    const callee = node.callee;
+    if (!callee)
+        return false;
+    // t(...)
+    if (callee.type === 'Identifier' && callee.value === 't')
+        return true;
+    // i18next.t(...)
+    if (callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        callee.property?.type === 'Identifier' &&
+        callee.property.value === 't' &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.value === 'i18next')
+        return true;
+    return false;
+}
 /**
  * Recursively visits AST nodes to find string literals.
  */
 function visitNodeForStrings(node, content, file, config, candidates) {
     if (!node)
         return;
+    // Skip already-instrumented t() / i18next.t() calls entirely so that
+    // strings inside the options object (defaultValue_one, etc.) are not
+    // picked up as new candidates on a second run.
+    if (node.type === 'CallExpression' && isTranslationCall(node))
+        return;
+    // Skip <Trans> elements (already instrumented)
+    if (node.type === 'JSXElement' && isTransComponent(node))
+        return;
     // Skip non-translatable JSX attributes entirely (e.g. className={...})
     if (node.type === 'JSXAttribute') {
         const nameNode = node.name;
@@ -633,6 +662,9 @@ function resolveExpressionName(expr, content, usedNames) {
 function detectJSXInterpolation(node, content, file, config, candidates) {
     if (!node)
         return;
+    // Skip <Trans> elements (already instrumented)
+    if (node.type === 'JSXElement' && isTransComponent(node))
+        return;
     const children = (node.type === 'JSXElement' || node.type === 'JSXFragment') ? node.children : null;
     if (children?.length > 1) {
         // Build "runs" of consecutive JSXText + simple-expression containers
@@ -645,6 +677,16 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
             else if (child.type === 'JSXExpressionContainer' && isSimpleJSXExpression(child.expression)) {
                 currentRun.push(child);
             }
+            else if (child.type === 'JSXExpressionContainer' &&
+                child.expression?.type === 'ConditionalExpression' &&
+                tryParsePluralTernary(child.expression, content)) {
+                // Plural ternary expression — include in the run for merged handling
+                currentRun.push(child);
+            }
+            else if (child.type === 'JSXElement' && isSimpleJSXElement(child)) {
+                // Simple HTML element — include in the run for Trans detection
+                currentRun.push(child);
+            }
             else {
                 // JSXElement, complex expression, etc. — break the run
                 if (currentRun.length > 0) {
@@ -659,49 +701,226 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
         for (const run of runs) {
             const hasText = run.some(c => c.type === 'JSXText' && c.value?.trim());
             const hasExpr = run.some(c => c.type === 'JSXExpressionContainer');
-            if (!hasText || !hasExpr || run.length < 2)
+            const hasElement = run.some(c => c.type === 'JSXElement');
+            // Require at least one text node plus either an expression or element
+            if (!hasText || run.length < 2)
                 continue;
-            // Build the interpolated text from the run
-            const usedNames = new Set();
-            const interpolations = [];
-            let text = '';
-            let valid = true;
+            if (!hasExpr && !hasElement)
+                continue;
+            // Check if any expression container in this run is a plural ternary
+            let pluralChild = null;
+            let pluralData = null;
             for (const child of run) {
-                if (child.type === 'JSXText') {
-                    text += content.slice(child.span.start, child.span.end);
+                if (child.type === 'JSXExpressionContainer' &&
+                    child.expression?.type === 'ConditionalExpression') {
+                    const p = tryParsePluralTernary(child.expression, content);
+                    if (p) {
+                        pluralChild = child;
+                        pluralData = p;
+                        break; // only one plural ternary per run
+                    }
                 }
-                else {
-                    const info = resolveExpressionName(child.expression, content, usedNames);
-                    if (!info) {
-                        valid = false;
-                        break;
+            }
+            if (hasElement) {
+                // ── JSX sibling run with nested HTML elements → <Trans> ──
+                const spanStart = run[0].span.start;
+                const spanEnd = run[run.length - 1].span.end;
+                // Build the translation string (with indexed tags) and text-only version (for scoring)
+                const usedNames = new Set();
+                const interpolations = [];
+                let transValue = '';
+                let textOnly = '';
+                let transContent = '';
+                let childIndex = 0;
+                let valid = true;
+                for (const child of run) {
+                    if (child.type === 'JSXText') {
+                        const raw = content.slice(child.span.start, child.span.end);
+                        transValue += raw;
+                        textOnly += raw;
+                        transContent += raw;
+                        childIndex++;
+                    }
+                    else if (child.type === 'JSXExpressionContainer') {
+                        const info = resolveExpressionName(child.expression, content, usedNames);
+                        if (!info) {
+                            valid = false;
+                            break;
+                        }
+                        transValue += `{{${info.name}}}`;
+                        textOnly += info.name;
+                        // In <Trans> children, simple expressions become {{ obj }} syntax
+                        const objExpr = info.name === info.expression ? info.name : `${info.name}: ${info.expression}`;
+                        transContent += `{{ ${objExpr} }}`;
+                        interpolations.push(info);
+                        childIndex++;
+                    }
+                    else if (child.type === 'JSXElement') {
+                        const innerText = getJSXElementTextContent(child, content);
+                        transValue += `<${childIndex}>${innerText}</${childIndex}>`;
+                        textOnly += innerText;
+                        // Keep the original JSX element source for the <Trans> children
+                        transContent += content.slice(child.span.start, child.span.end);
+                        childIndex++;
+                    }
+                }
+                if (!valid)
+                    continue;
+                const trimmedText = textOnly.trim();
+                const trimmedTransValue = transValue.trim();
+                if (!trimmedText || !trimmedTransValue)
+                    continue;
+                const candidate = stringDetector.detectCandidate(trimmedText, spanStart, spanEnd, file, content, config);
+                if (candidate) {
+                    candidate.type = 'jsx-mixed';
+                    candidate.content = transContent.trim();
+                    candidate.transValue = trimmedTransValue;
+                    if (interpolations.length > 0) {
+                        candidate.interpolations = interpolations;
+                    }
+                    // Mixed text + elements in JSX is almost always user-facing
+                    candidate.confidence = Math.min(1, candidate.confidence + 0.25);
+                    if (candidate.confidence >= 0.7) {
+                        // Remove individual candidates that overlap with the merged span
+                        for (let i = candidates.length - 1; i >= 0; i--) {
+                            if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
+                                candidates.splice(i, 1);
+                            }
+                        }
+                        candidates.push(candidate);
                     }
-                    text += `{{${info.name}}}`;
-                    interpolations.push(info);
                 }
             }
-            if (!valid)
-                continue;
-            const trimmed = text.trim();
-            if (!trimmed || interpolations.length === 0)
-                continue;
-            const spanStart = run[0].span.start;
-            const spanEnd = run[run.length - 1].span.end;
-            const candidate = stringDetector.detectCandidate(trimmed, spanStart, spanEnd, file, content, config);
-            if (candidate) {
-                candidate.type = 'jsx-text';
-                candidate.content = trimmed;
-                candidate.interpolations = interpolations;
-                // Mixed text + expressions in JSX is almost always user-facing
-                candidate.confidence = Math.min(1, candidate.confidence + 0.2);
-                if (candidate.confidence >= 0.7) {
-                    // Remove individual candidates that overlap with the merged span
-                    for (let i = candidates.length - 1; i >= 0; i--) {
-                        if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
-                            candidates.splice(i, 1);
+            else if (pluralChild && pluralData) {
+                // ── JSX sibling run with embedded plural ternary ──
+                const countExpr = pluralData.countExpression;
+                // Resolve names for non-count, non-plural expressions
+                const usedNames = new Set();
+                const extraInterpolations = [];
+                const exprNameMap = new Map();
+                let valid = true;
+                for (const child of run) {
+                    if (child.type === 'JSXExpressionContainer' && child !== pluralChild) {
+                        const exprText = content.slice(child.expression.span.start, child.expression.span.end);
+                        if (exprText === countExpr) {
+                            exprNameMap.set(child, 'count');
+                        }
+                        else {
+                            const info = resolveExpressionName(child.expression, content, usedNames);
+                            if (!info) {
+                                valid = false;
+                                break;
+                            }
+                            exprNameMap.set(child, info.name);
+                            extraInterpolations.push(info);
                         }
                     }
-                    candidates.push(candidate);
+                }
+                if (!valid)
+                    continue;
+                // Build merged text for each plural form
+                const forms = [
+                    ...(pluralData.zero !== undefined ? ['zero'] : []),
+                    ...(pluralData.one !== undefined ? ['one'] : []),
+                    'other'
+                ];
+                const formTexts = {};
+                for (const form of forms) {
+                    let text = '';
+                    for (const child of run) {
+                        if (child.type === 'JSXText') {
+                            text += content.slice(child.span.start, child.span.end);
+                        }
+                        else if (child === pluralChild) {
+                            const formText = form === 'zero'
+                                ? pluralData.zero
+                                : form === 'one'
+                                    ? pluralData.one
+                                    : pluralData.other;
+                            text += formText;
+                        }
+                        else {
+                            const name = exprNameMap.get(child);
+                            text += `{{${name}}}`;
+                        }
+                    }
+                    formTexts[form] = text.trim();
+                }
+                const spanStart = run[0].span.start;
+                const spanEnd = run[run.length - 1].span.end;
+                const otherText = formTexts.other;
+                if (!otherText)
+                    continue;
+                const candidate = stringDetector.detectCandidate(otherText, spanStart, spanEnd, file, content, config);
+                if (candidate) {
+                    candidate.type = 'jsx-text';
+                    candidate.content = otherText;
+                    candidate.pluralForms = {
+                        countExpression: countExpr,
+                        zero: formTexts.zero,
+                        one: formTexts.one,
+                        other: otherText
+                    };
+                    if (extraInterpolations.length > 0) {
+                        candidate.interpolations = extraInterpolations;
+                    }
+                    // Plural + JSX merge is always user-facing
+                    candidate.confidence = Math.min(1, candidate.confidence + 0.3);
+                    if (candidate.confidence >= 0.7) {
+                        // Remove individual candidates that overlap with the merged span
+                        for (let i = candidates.length - 1; i >= 0; i--) {
+                            if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
+                                candidates.splice(i, 1);
+                            }
+                        }
+                        candidates.push(candidate);
+                    }
+                }
+            }
+            else {
+                // ── Original JSX sibling merging (text + expressions, no elements) ──
+                // Build the interpolated text from the run
+                const usedNames = new Set();
+                const interpolations = [];
+                let text = '';
+                let valid = true;
+                for (const child of run) {
+                    if (child.type === 'JSXText') {
+                        text += content.slice(child.span.start, child.span.end);
+                    }
+                    else {
+                        const info = resolveExpressionName(child.expression, content, usedNames);
+                        if (!info) {
+                            valid = false;
+                            break;
+                        }
+                        text += `{{${info.name}}}`;
+                        interpolations.push(info);
+                    }
+                }
+                if (!valid)
+                    continue;
+                const trimmed = text.trim();
+                if (!trimmed || interpolations.length === 0)
+                    continue;
+                const spanStart = run[0].span.start;
+                const spanEnd = run[run.length - 1].span.end;
+                const candidate = stringDetector.detectCandidate(trimmed, spanStart, spanEnd, file, content, config);
+                if (candidate) {
+                    candidate.type = 'jsx-text';
+                    candidate.content = trimmed;
+                    candidate.interpolations = interpolations;
+                    // Mixed text + expressions in JSX is almost always user-facing
+                    candidate.confidence = Math.min(1, candidate.confidence + 0.2);
+                    if (candidate.confidence >= 0.7) {
+                        // Remove individual candidates that overlap with the merged span
+                        for (let i = candidates.length - 1; i >= 0; i--) {
+                            if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
+                                candidates.splice(i, 1);
+                            }
+                        }
+                        candidates.push(candidate);
+                    }
                 }
             }
         }
@@ -732,6 +951,59 @@ function isSimpleJSXExpression(expr) {
         return true;
     return false;
 }
+/**
+ * Returns true when a JSXElement is "simple" enough to be included in a
+ * `<Trans>` JSX sibling run.  Accepts:
+ * - Self-closing elements (`<br />`, `<img />`)
+ * - Elements whose only children are `JSXText` nodes
+ * Only HTML-like elements (lowercase tag name) are accepted; React
+ * components (uppercase, e.g. `<Button />`) break the run.
+ */
+function isSimpleJSXElement(node) {
+    if (node.type !== 'JSXElement')
+        return false;
+    const namePart = node.opening?.name;
+    if (!namePart)
+        return false;
+    // Only include HTML-like elements (lowercase first char)
+    let tagName = null;
+    if (namePart.type === 'Identifier') {
+        tagName = namePart.value;
+    }
+    if (!tagName || tagName[0] !== tagName[0].toLowerCase())
+        return false;
+    // Self-closing elements are simple
+    if (node.opening?.selfClosing)
+        return true;
+    // Elements with only text children (or empty) are simple
+    const children = node.children || [];
+    return children.length === 0 || children.every((c) => c.type === 'JSXText');
+}
+/**
+ * Returns the text content of a simple JSXElement's children.
+ */
+function getJSXElementTextContent(node, content) {
+    const children = node.children || [];
+    return children
+        .filter((c) => c.type === 'JSXText')
+        .map((c) => content.slice(c.span.start, c.span.end))
+        .join('');
+}
+/**
+ * Returns true when a JSXElement is a `<Trans>` component
+ * (already instrumented content).
+ */
+function isTransComponent(node) {
+    const opening = node.opening;
+    if (!opening)
+        return false;
+    const name = opening.name;
+    if (name?.type === 'Identifier' && name.value === 'Trans')
+        return true;
+    if (name?.type === 'JSXMemberExpression' && name.property?.type === 'Identifier' && name.property.value === 'Trans')
+        return true;
+    return false;
+}
 // ─── Plural conditional pattern detection ────────────────────────────────────
 /**
  * Extracts the text value from a string literal or static template literal node.
@@ -838,6 +1110,11 @@ function detectPluralPatterns(node, content, file, config, candidates) {
             // Use the "other" form as the candidate content (with {{count}})
             const spanStart = node.span.start;
             const spanEnd = node.span.end;
+            // Skip if this ternary is already covered by a wider candidate
+            // (e.g. a JSX sibling run that merged surrounding text with this plural)
+            const alreadyHandled = candidates.some(c => c.pluralForms && c.offset <= spanStart && c.endOffset >= spanEnd);
+            if (alreadyHandled)
+                return;
             const candidate = stringDetector.detectCandidate(plural.other, spanStart, spanEnd, file, content, config);
             if (candidate) {
                 candidate.type = 'string-literal';
@@ -1451,7 +1728,7 @@ async function writeExtractedKeys(candidates, config, namespace, logger$1 = new
                 translations[`${candidate.key}_other`] = pf.other;
             }
             else {
-                translations[candidate.key] = candidate.content;
+                translations[candidate.key] = candidate.transValue ?? candidate.content;
             }
         }
     }

package/dist/cjs/instrumenter/core/transformer.js

@@ -29,6 +29,7 @@ function transformFile(content, file, candidates, options) {
     const transformedComponents = new Set();
     let hasComponentCandidates = false;
     let hasNonComponentCandidates = false;
+    let hasTransCandidates = false;
     // ── Language-change site injections ────────────────────────────────────
     const languageChangeSites = options.languageChangeSites || [];
     // Track components that need `i18n` from useTranslation()
@@ -82,9 +83,15 @@ function transformFile(content, file, candidates, options) {
             if (replacement) {
                 s.overwrite(candidate.offset, candidate.endOffset, replacement);
                 transformCount++;
+                if (candidate.type === 'jsx-mixed') {
+                    hasTransCandidates = true;
+                }
                 if (candidate.insideComponent) {
-                    transformedComponents.add(candidate.insideComponent);
-                    hasComponentCandidates = true;
+                    // jsx-mixed candidates use <Trans>, not t(), so they don't need useTranslation
+                    if (candidate.type !== 'jsx-mixed') {
+                        transformedComponents.add(candidate.insideComponent);
+                        hasComponentCandidates = true;
+                    }
                 }
                 else {
                     hasNonComponentCandidates = true;
@@ -108,17 +115,20 @@ function transformFile(content, file, candidates, options) {
                 const indent = detectIndent(content, comp.bodyStart);
                 const defaultNS = options.config.extract?.defaultNS ?? 'translation';
                 const nsArg = (options.namespace && options.namespace !== defaultNS) ? `'${options.namespace}'` : '';
-                // Build destructuring: include `t` if the component has string candidates,
+                // Build destructuring: include `t` if the component has string candidates
+                // (but not jsx-mixed which use <Trans>),
                 // include `i18n` if the component has language-change sites.
-                const needsT = highConfidenceCandidates.some(c => c.insideComponent === comp.name);
+                const needsT = highConfidenceCandidates.some(c => c.insideComponent === comp.name && c.type !== 'jsx-mixed');
                 const needsI18n = componentsNeedingI18n.has(comp.name);
                 const parts = [];
                 if (needsT)
                     parts.push('t');
                 if (needsI18n)
                     parts.push('i18n');
-                if (parts.length === 0)
-                    parts.push('t'); // fallback
+                // Skip if component needs neither t nor i18n
+                // (e.g. component only has jsx-mixed / <Trans> candidates)
+                if (!needsT && !needsI18n)
+                    continue;
                 const destructured = `{ ${parts.join(', ')} }`;
                 s.appendRight(comp.bodyStart + 1, `\n${indent}const ${destructured} = useTranslation(${nsArg})`);
                 injections.hookInjected = true;
@@ -148,7 +158,8 @@ function transformFile(content, file, candidates, options) {
         // Add import statements
         addImportStatements(s, content, {
             needsUseTranslation: hasComponentCandidates && options.hasReact,
-            needsI18next: hasNonComponentCandidates || !options.hasReact
+            needsI18next: hasNonComponentCandidates || !options.hasReact,
+            needsTrans: hasTransCandidates && options.hasReact
         });
         injections.importAdded = true;
     }
@@ -196,6 +207,12 @@ function buildReplacement(candidate, key, useHookStyle, namespace) {
         }
         optionEntries.push(`defaultValue_other: '${escapeString(pf.other)}'`);
         optionEntries.push(`count: ${pf.countExpression}`);
+        // Add extra interpolation variables (e.g. from JSX sibling merging with plurals)
+        if (candidate.interpolations?.length) {
+            for (const interp of candidate.interpolations) {
+                optionEntries.push(interp.name === interp.expression ? interp.name : `${interp.name}: ${interp.expression}`);
+            }
+        }
         if (!useHookStyle && namespace) {
             optionEntries.push(`ns: '${namespace}'`);
         }
@@ -226,7 +243,8 @@ function buildReplacement(candidate, key, useHookStyle, namespace) {
             return `{${tCall}}`;
         case 'jsx-mixed':
             if (useHookStyle) {
-                return `<Trans i18nKey="${key}">${candidate.content}</Trans>`;
+                const nsAttr = namespace ? ` ns="${namespace}"` : '';
+                return `<Trans i18nKey="${key}"${nsAttr}>${candidate.content}</Trans>`;
             }
             return candidate.content;
         case 'template-literal':
@@ -280,12 +298,24 @@ function detectIndent(content, braceOffset) {
     return '  ';
 }
 /**
- * Adds necessary import statements (useTranslation and/or i18next).
+ * Adds necessary import statements (useTranslation, Trans, and/or i18next).
  */
 function addImportStatements(s, content, needs) {
     let importStatement = '';
-    if (needs.needsUseTranslation && !hasImport(content, 'react-i18next')) {
-        importStatement += "import { useTranslation } from 'react-i18next'\n";
+    // Build a combined react-i18next import
+    const reactI18nextImports = [];
+    if (needs.needsUseTranslation)
+        reactI18nextImports.push('useTranslation');
+    if (needs.needsTrans)
+        reactI18nextImports.push('Trans');
+    if (reactI18nextImports.length > 0) {
+        if (!hasImport(content, 'react-i18next')) {
+            importStatement += `import { ${reactI18nextImports.join(', ')} } from 'react-i18next'\n`;
+        }
+        else {
+            // react-i18next is already imported — augment with any missing named exports
+            augmentReactI18nextImport(s, content, reactI18nextImports);
+        }
     }
     if (needs.needsI18next && !hasImport(content, 'i18next')) {
         importStatement += "import i18next from 'i18next'\n";
@@ -310,6 +340,24 @@ function addImportStatements(s, content, needs) {
     }
     s.appendRight(insertPos, importStatement);
 }
+/**
+ * Augments an existing `import { ... } from 'react-i18next'` with any missing
+ * named exports (e.g. adds `Trans` when only `useTranslation` is imported).
+ */
+function augmentReactI18nextImport(s, content, needed) {
+    const importMatch = /import\s*\{([^}]*)\}\s*from\s*['"]react-i18next['"]/.exec(content);
+    if (!importMatch)
+        return;
+    const existingImports = importMatch[1].split(',').map(x => x.trim()).filter(Boolean);
+    const toAdd = needed.filter(n => !existingImports.includes(n));
+    if (toAdd.length === 0)
+        return;
+    const newImports = [...existingImports, ...toAdd].join(', ');
+    const newImportStatement = `import { ${newImports} } from 'react-i18next'`;
+    const matchStart = importMatch.index;
+    const matchEnd = matchStart + importMatch[0].length;
+    s.overwrite(matchStart, matchEnd, newImportStatement);
+}
 /**
  * Generates a unified diff showing what changed.
  */

package/dist/cjs/linter.js

@@ -101,6 +101,34 @@ function isI18nextOptionKey(key) {
         return true;
     return false;
 }
+// ─── Ignore-comment helpers ──────────────────────────────────────────────────
+/**
+ * Regex matching the shared ignore directive used by both the instrumenter and
+ * the linter.  Supports both `-next-line` and inline variants, in line or block
+ * comment form.
+ *
+ *   // i18next-instrument-ignore-next-line   → suppresses the following line
+ *   // i18next-instrument-ignore             → suppresses the following line
+ *   { /* i18next-instrument-ignore * / }     → same, block-comment form
+ */
+const LINT_IGNORE_RE = /i18next-instrument-ignore(?:-next-line)?/;
+/**
+ * Scans `code` for ignore-directive comments and returns a Set of 1-based
+ * line numbers whose issues should be suppressed.
+ *
+ * The directive always suppresses the **next** line (line N+1), matching the
+ * behaviour of the instrumenter's `collectIgnoredLines`.
+ */
+function collectLintIgnoredLines(code) {
+    const ignored = new Set();
+    const lines = code.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (LINT_IGNORE_RE.test(lines[i])) {
+            ignored.add(i + 2); // 1-based: directive is on line i+1, suppressed line is i+2
+        }
+    }
+    return ignored;
+}
 // Helper to lint interpolation parameter errors in t() calls
 function lintInterpolationParams(ast, code, config, translationValues) {
     const issues = [];
@@ -168,14 +196,27 @@ function lintInterpolationParams(ast, code, config, translationValues) {
             // Support both .expression and direct node for arguments
             const arg0raw = node.arguments?.[0];
             const arg1raw = node.arguments?.[1];
+            const arg2raw = node.arguments?.[2];
             const arg0 = arg0raw?.expression ?? arg0raw;
             const arg1 = arg1raw?.expression ?? arg1raw;
-            // Only check interpolation params if the first argument is a string literal (translation key or string)
+            const arg2 = arg2raw?.expression ?? arg2raw;
+            // Only check interpolation params if the first argument is a string literal
             if (arg0?.type === 'StringLiteral') {
                 const keyOrStr = arg0.value;
+                // Detect 3-argument form: t('key', 'Default string {{foo}}', { foo })
+                // In this form arg1 is the default string and arg2 is the params object.
+                const isThreeArgForm = arg1?.type === 'StringLiteral' && arg2 !== undefined;
+                const translationArg = isThreeArgForm ? arg1 : arg0;
+                const paramsArg = isThreeArgForm ? arg2 : arg1;
+                // If a params argument exists but is NOT an object literal (e.g. it's a variable),
+                // we cannot statically determine its keys — skip the interpolation check to avoid
+                // false positives.
+                if (paramsArg && paramsArg.type !== 'ObjectExpression') {
+                    return;
+                }
                 let paramKeys = [];
-                if (arg1?.type === 'ObjectExpression') {
-                    paramKeys = arg1.properties
+                if (paramsArg?.type === 'ObjectExpression') {
+                    paramKeys = paramsArg.properties
                         .map((p) => {
                         // Standard key:value property like { name: "value" }
                         if (p.type === 'KeyValueProperty' && p.key) {
@@ -195,10 +236,17 @@ function lintInterpolationParams(ast, code, config, translationValues) {
                 }
                 if (!Array.isArray(paramKeys))
                     paramKeys = [];
-                // Resolve the actual translation string to check against:
-                // fix — if the first arg is a lookup key (no interpolation markers of its own)
-                // and we have a loaded translation map, use the translated value instead.
-                const resolvedStr = translationValues?.get(keyOrStr) ?? keyOrStr;
+                // Resolve the actual translation string:
+                // - For 3-arg form: the default string is always arg1 (use it directly)
+                // - For 2-arg / 1-arg form: if arg0 is a lookup key (no interpolation markers),
+                //   try to resolve it from the loaded translation map.
+                let resolvedStr;
+                if (isThreeArgForm) {
+                    resolvedStr = translationArg.value;
+                }
+                else {
+                    resolvedStr = translationValues?.get(keyOrStr) ?? keyOrStr;
+                }
                 const searchText = arg0.raw ?? `"${arg0.value}"`;
                 callSites.push({ translationStr: resolvedStr, searchText, paramKeys });
             }
@@ -360,6 +408,12 @@ class Linter extends node_events.EventEmitter {
                 // Collect interpolation parameter issues
                 const interpolationIssues = lintInterpolationParams(ast, code, config, translationValues);
                 let allIssues = [...hardcodedStrings, ...interpolationIssues];
+                // Filter issues suppressed by ignore-directive comments.
+                // The directive on line N suppresses all issues reported on line N+1.
+                const ignoredLines = collectLintIgnoredLines(code);
+                if (ignoredLines.size > 0) {
+                    allIssues = allIssues.filter(issue => !ignoredLines.has(issue.line));
+                }
                 allIssues = await this.runLintOnResultPipeline(file, allIssues, plugins);
                 if (allIssues.length > 0) {
                     totalIssues += allIssues.length;