i18next-cli 1.59.1 → 1.61.0

package/README.md

@@ -204,6 +204,8 @@ npx i18next-cli extract --watch --with-types
 
 Displays a health check of your project's translation status. Can run without a config file. Exits with a non-zero status code when translations are missing.
 
+The primary language is checked too: any key used in your code but absent from the primary language's translation files (a typo, or `extract` was never run) is reported and causes a non-zero exit code. Empty-string placeholders written by `extract` are considered present and do not fail the check. Running `npx i18next-cli status <primaryLanguage>` shows the absent keys in detail.
+
 **Options:**
 - `--namespace <ns>, -n <ns>`: Filter the report by a specific namespace.
 - `--hide-translated`: Hide already translated keys in the detailed view, showing only missing translations.
@@ -280,6 +282,8 @@ Analyzes your source code for internationalization issues like hardcoded strings
 npx i18next-cli lint
 ```
 
+To suppress warnings for code you intentionally aren't translating yet, use the [`i18next-instrument-ignore` directive](#suppressing-detection-with-i18next-instrument-ignore) — the same comment recognized by the `instrument` command.
+
 ### `instrument`
 
 Scans your source code for hardcoded user-facing strings and instruments them with i18next translation calls. This is useful for adding i18next instrumentation to an existing codebase that wasn't built with internationalization in mind. You can see this in action in [this video](https://youtu.be/aWZnZXwGg34) or in [this blog post](https://www.locize.com/blog/i18next-cli-instrument?utm_source=i18next_cli_readme&utm_medium=github&utm_campaign=readme).
@@ -437,6 +441,33 @@ The intended usage pattern is:
 5. Manually fix any false positives or false negatives
 6. Run `extract` to finalize translation files
 
+#### Suppressing detection with `i18next-instrument-ignore`
+
+Both the `lint` and `instrument` commands honor an ignore comment so you can skip placeholder or intentionally-untranslated content. It works as a line or block comment, including the JSX `{/* ... */}` form, and comes in two variants:
+
+| Directive | Scope |
+| --- | --- |
+| `i18next-instrument-ignore` | The **entire JSX element** that begins on the next line — its opening tag, all nested children, and its closing tag. Falls back to a single line when the next line isn't a JSX element (e.g. a plain `t()` call). |
+| `i18next-instrument-ignore-next-line` | Only the **single line** immediately after the directive. |
+
+```jsx
+// Suppress a whole element (including multi-line opening tags and nested children)
+{/* i18next-instrument-ignore */}
+<div
+  css={css`text-align: center;`}>
+  Hi, I'm Bob 👋
+  <p>This nested text is ignored too</p>
+</div>
+
+// Suppress just one line
+{/* i18next-instrument-ignore-next-line */}
+<p>Only this line is ignored</p>
+
+// Also works for t() interpolation warnings in the linter
+// i18next-instrument-ignore
+const msg = t('Hello {{name}}!', { wrong: 'world' })
+```
+
 ### `migrate-config`
 Automatically migrates a legacy `i18next-parser.config.js` file to the new `i18next.config.ts` format.
 

package/dist/cjs/cli.js

@@ -32,7 +32,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.59.1'); // This string is replaced with the actual version at build time by rollup
+    .version('1.61.0'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program

package/dist/cjs/extractor/parsers/ast-utils.js

@@ -103,6 +103,172 @@ function lineColumnFromOffset(code, offset) {
         column: lines[lines.length - 1].length
     };
 }
+// ─── Byte → char offset helpers ────────────────────────────────────────────
+/**
+ * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
+ * indices (UTF-16 code-unit positions).
+ *
+ * SWC internally represents source as UTF-8 and reports AST spans as byte
+ * offsets into that representation.  MagicString and all JavaScript String
+ * methods operate on UTF-16 code-unit indices.  For files that contain only
+ * ASCII characters the two coincide, so this function returns `null` as a
+ * fast path.  For files with multi-byte characters (emoji, accented letters,
+ * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
+ */
+function buildByteToCharMap(content) {
+    // Fast path: pure ASCII means byte offset ≡ char index
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(content))
+        return null;
+    const map = [];
+    let byteIdx = 0;
+    for (let charIdx = 0; charIdx < content.length;) {
+        const cp = content.codePointAt(charIdx);
+        const byteLen = cp <= 0x7F ? 1 : cp <= 0x7FF ? 2 : cp <= 0xFFFF ? 3 : 4;
+        const charLen = cp > 0xFFFF ? 2 : 1; // surrogate pair
+        // Every byte belonging to this character maps to the same char index
+        for (let b = 0; b < byteLen; b++) {
+            map[byteIdx + b] = charIdx;
+        }
+        byteIdx += byteLen;
+        charIdx += charLen;
+    }
+    // Sentinel so that span.end (one-past-the-last-byte) resolves correctly
+    map[byteIdx] = content.length;
+    return map;
+}
+/**
+ * Recursively converts every `span.start` / `span.end` in an SWC AST from
+ * UTF-8 byte offsets to JavaScript string character indices using the
+ * pre-built lookup table.
+ */
+function convertSpansToCharIndices(node, byteToChar) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (node.span && typeof node.span.start === 'number') {
+        const charStart = byteToChar[node.span.start];
+        const charEnd = byteToChar[node.span.end];
+        if (charStart !== undefined && charEnd !== undefined) {
+            node.span = { ...node.span, start: charStart, end: charEnd };
+        }
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'span')
+            continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) {
+                if (item && typeof item === 'object') {
+                    convertSpansToCharIndices(item, byteToChar);
+                }
+            }
+        }
+        else if (child && typeof child === 'object') {
+            convertSpansToCharIndices(child, byteToChar);
+        }
+    }
+}
+// ─── Ignore-comment helpers ──────────────────────────────────────────────────
+/**
+ * Matches the shared ignore directive used by both the instrumenter and the
+ * linter. The optional `-next-line` suffix is captured in group 1:
+ *
+ *   i18next-instrument-ignore-next-line  → suppress only the single next line
+ *   i18next-instrument-ignore            → suppress the whole next JSX element
+ *
+ * Works in line-comment (`// ...`) and block-comment form, including the JSX
+ * `{ /* ... * / }` form.
+ */
+const IGNORE_DIRECTIVE_RE = /i18next-instrument-ignore(-next-line)?/;
+/**
+ * Scans `code` for ignore-directive comments and returns a Set of 1-based line
+ * numbers whose issues/strings should be suppressed.
+ *
+ * A directive on line `D` targets the following line `D + 1`. The behaviour
+ * depends on the directive variant:
+ *
+ *   - `i18next-instrument-ignore-next-line` suppresses only line `D + 1`.
+ *   - `i18next-instrument-ignore` suppresses the **entire JSX element** that
+ *     begins on line `D + 1` — i.e. every line from its opening tag through its
+ *     closing tag, including nested children. This makes a single directive
+ *     cover multi-line elements (e.g. `<div … css={…}>…</div>`) and elements
+ *     with nested children, instead of just the one physical line after it.
+ *
+ * When no AST node begins on the targeted line (e.g. the next line is a plain
+ * `t()` call rather than a JSX element), block scope falls back to suppressing
+ * the single targeted line, preserving the original line-based behaviour.
+ *
+ * `ast` spans must already be normalised to file-relative character indices
+ * (see {@link normalizeASTSpans} / {@link convertSpansToCharIndices}).
+ */
+function collectIgnoredLineRanges(ast, code) {
+    const ignored = new Set();
+    const lines = code.split('\n');
+    // 1-based target lines, split by directive variant.
+    const blockTargets = new Set();
+    const lineTargets = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const match = IGNORE_DIRECTIVE_RE.exec(lines[i]);
+        if (!match)
+            continue;
+        const target = i + 2; // directive on line i+1 (1-based) → target line i+2
+        if (match[1])
+            lineTargets.add(target); // `-next-line` variant
+        else
+            blockTargets.add(target);
+    }
+    if (blockTargets.size === 0 && lineTargets.size === 0)
+        return ignored;
+    // Always suppress the directly targeted line. For `-next-line` this is the
+    // whole effect; for block directives it is the fallback when no element is
+    // found, and otherwise the start of the suppressed range.
+    for (const target of lineTargets)
+        ignored.add(target);
+    for (const target of blockTargets)
+        ignored.add(target);
+    if (blockTargets.size === 0)
+        return ignored;
+    // For block directives, find the widest AST node that begins on the targeted
+    // line and expand suppression to cover its full line span. Multiple nodes can
+    // start on the same line (e.g. a JSXElement and its JSXOpeningElement); taking
+    // the largest end line picks the outermost element.
+    const widestEndLineByStartLine = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (node.span && typeof node.span.start === 'number') {
+            const start = lineColumnFromOffset(code, node.span.start);
+            if (start && blockTargets.has(start.line)) {
+                const end = lineColumnFromOffset(code, node.span.end);
+                if (end) {
+                    const prev = widestEndLineByStartLine.get(start.line);
+                    if (prev === undefined || end.line > prev) {
+                        widestEndLineByStartLine.set(start.line, end.line);
+                    }
+                }
+            }
+        }
+        for (const key of Object.keys(node)) {
+            if (key === 'span')
+                continue;
+            const child = node[key];
+            if (Array.isArray(child)) {
+                for (const item of child)
+                    visit(item);
+            }
+            else if (child && typeof child === 'object') {
+                visit(child);
+            }
+        }
+    };
+    visit(ast);
+    for (const target of blockTargets) {
+        const endLine = widestEndLineByStartLine.get(target) ?? target;
+        for (let line = target; line <= endLine; line++)
+            ignored.add(line);
+    }
+    return ignored;
+}
 /**
  * Finds and returns the full property node (KeyValueProperty) for the given
  * property name from an ObjectExpression.
@@ -189,6 +355,9 @@ function getObjectPropValue(object, propName, identifierResolver) {
     return undefined;
 }
 
+exports.buildByteToCharMap = buildByteToCharMap;
+exports.collectIgnoredLineRanges = collectIgnoredLineRanges;
+exports.convertSpansToCharIndices = convertSpansToCharIndices;
 exports.findFirstTokenIndex = findFirstTokenIndex;
 exports.getObjectPropValue = getObjectPropValue;
 exports.getObjectPropValueExpression = getObjectPropValueExpression;

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

@@ -262,9 +262,9 @@ async function scanFileForCandidates(content, file, config) {
         // SWC reports spans as UTF-8 byte offsets, but JavaScript strings and
         // MagicString use UTF-16 code-unit indices. Without this conversion,
         // every emoji / accented char / CJK char shifts all subsequent offsets.
-        const byteToChar = buildByteToCharMap(content);
+        const byteToChar = astUtils.buildByteToCharMap(content);
         if (byteToChar) {
-            convertSpansToCharIndices(ast, byteToChar);
+            astUtils.convertSpansToCharIndices(ast, byteToChar);
         }
         // Detect React function component boundaries
         detectComponentBoundaries(ast, content, components);
@@ -296,11 +296,13 @@ async function scanFileForCandidates(content, file, config) {
         }
         // Filter out candidates suppressed by ignore-comment directives.
         // Supported comments (line or block):
-        //   // i18next-instrument-ignore-next-line
-        //   // i18next-instrument-ignore
+        //   // i18next-instrument-ignore-next-line  → suppress the single next line
+        //   // i18next-instrument-ignore            → suppress the whole next JSX element
         //   /* i18next-instrument-ignore-next-line */
         //   /* i18next-instrument-ignore */
-        const ignoredLines = collectIgnoredLines(content);
+        // AST spans were normalised to char indices above, so the shared helper can
+        // resolve element line ranges directly.
+        const ignoredLines = astUtils.collectIgnoredLineRanges(ast, content);
         if (ignoredLines.size > 0) {
             const keep = [];
             for (const c of candidates) {
@@ -318,32 +320,6 @@ async function scanFileForCandidates(content, file, config) {
     }
     return { candidates, components, languageChangeSites };
 }
-// ─── Ignore-comment helpers ──────────────────────────────────────────────────
-/**
- * Regex that matches a directive comment requesting the instrumenter to skip
- * the **next** line. Works with both line comments (`// ...`) and block
- * comments. The supported directives are:
- *
- *   i18next-instrument-ignore-next-line
- *   i18next-instrument-ignore
- */
-const IGNORE_RE = /i18next-instrument-ignore(?:-next-line)?/;
-/**
- * Scans `content` for ignore-directive comments and returns a Set of 1-based
- * line numbers whose strings should be excluded from instrumentation.
- */
-function collectIgnoredLines(content) {
-    const ignored = new Set();
-    const lines = content.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        if (IGNORE_RE.test(lines[i])) {
-            // Directive on line i → suppress the *following* line (i + 1)
-            // We store 1-based line numbers, so the suppressed line is i + 2
-            ignored.add(i + 2);
-        }
-    }
-    return ignored;
-}
 /**
  * Returns the 1-based line number for a character offset.
  */
@@ -1964,71 +1940,6 @@ async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugin
     }
     return candidates;
 }
-// ─── Byte → char offset helpers ────────────────────────────────────────────
-/**
- * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
- * indices (UTF-16 code-unit positions).
- *
- * SWC internally represents source as UTF-8 and reports AST spans as byte
- * offsets into that representation.  MagicString and all JavaScript String
- * methods operate on UTF-16 code-unit indices.  For files that contain only
- * ASCII characters the two coincide, so this function returns `null` as a
- * fast path.  For files with multi-byte characters (emoji, accented letters,
- * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
- */
-function buildByteToCharMap(content) {
-    // Fast path: pure ASCII means byte offset ≡ char index
-    // eslint-disable-next-line no-control-regex
-    if (!/[^\x00-\x7F]/.test(content))
-        return null;
-    const map = [];
-    let byteIdx = 0;
-    for (let charIdx = 0; charIdx < content.length;) {
-        const cp = content.codePointAt(charIdx);
-        const byteLen = cp <= 0x7F ? 1 : cp <= 0x7FF ? 2 : cp <= 0xFFFF ? 3 : 4;
-        const charLen = cp > 0xFFFF ? 2 : 1; // surrogate pair
-        // Every byte belonging to this character maps to the same char index
-        for (let b = 0; b < byteLen; b++) {
-            map[byteIdx + b] = charIdx;
-        }
-        byteIdx += byteLen;
-        charIdx += charLen;
-    }
-    // Sentinel so that span.end (one-past-the-last-byte) resolves correctly
-    map[byteIdx] = content.length;
-    return map;
-}
-/**
- * Recursively converts every `span.start` / `span.end` in an SWC AST from
- * UTF-8 byte offsets to JavaScript string character indices using the
- * pre-built lookup table.
- */
-function convertSpansToCharIndices(node, byteToChar) {
-    if (!node || typeof node !== 'object')
-        return;
-    if (node.span && typeof node.span.start === 'number') {
-        const charStart = byteToChar[node.span.start];
-        const charEnd = byteToChar[node.span.end];
-        if (charStart !== undefined && charEnd !== undefined) {
-            node.span = { ...node.span, start: charStart, end: charEnd };
-        }
-    }
-    for (const key of Object.keys(node)) {
-        if (key === 'span')
-            continue;
-        const child = node[key];
-        if (Array.isArray(child)) {
-            for (const item of child) {
-                if (item && typeof item === 'object') {
-                    convertSpansToCharIndices(item, byteToChar);
-                }
-            }
-        }
-        else if (child && typeof child === 'object') {
-            convertSpansToCharIndices(child, byteToChar);
-        }
-    }
-}
 
 exports.runInstrumenter = runInstrumenter;
 exports.writeExtractedKeys = writeExtractedKeys;

package/dist/cjs/linter.js

@@ -9,6 +9,7 @@ var node_util = require('node:util');
 var logger = require('./utils/logger.js');
 var wrapOra = require('./utils/wrap-ora.js');
 var jsxAttributes = require('./utils/jsx-attributes.js');
+var astUtils = require('./extractor/parsers/ast-utils.js');
 
 /**
  * Loads all translation values from the primary locale's JSON files and returns
@@ -101,34 +102,6 @@ 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 = [];
@@ -403,14 +376,30 @@ class Linter extends node_events.EventEmitter {
                         continue;
                     }
                 }
+                // Normalise AST spans to file-relative character indices so the ignore
+                // directive can resolve the line range of the JSX element it precedes.
+                // (findHardcodedStrings/lintInterpolationParams locate issues via text
+                // search and don't read spans, so this only affects ignore handling.)
+                try {
+                    const spanBase = ast.span.start - astUtils.findFirstTokenIndex(code);
+                    astUtils.normalizeASTSpans(ast, spanBase);
+                    const byteToChar = astUtils.buildByteToCharMap(code);
+                    if (byteToChar)
+                        astUtils.convertSpansToCharIndices(ast, byteToChar);
+                }
+                catch {
+                    // If span normalisation fails for any reason, fall back to text-based
+                    // issue detection without block-scoped ignore support.
+                }
                 // Collect hardcoded string issues
                 const hardcodedStrings = findHardcodedStrings(ast, code, config);
                 // 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);
+                //   i18next-instrument-ignore-next-line → suppresses the single next line
+                //   i18next-instrument-ignore           → suppresses the whole next JSX element
+                const ignoredLines = astUtils.collectIgnoredLineRanges(ast, code);
                 if (ignoredLines.size > 0) {
                     allIssues = allIssues.filter(issue => !ignoredLines.has(issue.line));
                 }

package/dist/cjs/status.js

@@ -56,6 +56,11 @@ async function runStatus(config, options = {}) {
                 break;
             }
         }
+        // The primary language fails the check only on absent keys (used in code but
+        // missing from the translation file); empty placeholders are tolerated.
+        if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
+            hasMissing = true;
+        }
         if (hasMissing) {
             spinner.fail('Error: Incomplete translations detected.');
             process.exit(1);
@@ -203,7 +208,13 @@ async function generateStatusReport(config) {
         if (nestedRefKeys.length > 0)
             nestedReferenceKeysByNs.set(ns, nestedRefKeys);
     }
-    for (const locale of secondaryLanguages) {
+    // The primary language is checked first so that keys used in code but absent
+    // from the primary translation file (e.g. a typo, or `extract` never run) are
+    // surfaced as well. For the primary, an empty value is a deliberate
+    // placeholder and counts as present — only truly absent keys are flagged.
+    const localesToCheck = [primaryLanguage, ...secondaryLanguages.filter((l) => l !== primaryLanguage)];
+    for (const locale of localesToCheck) {
+        const isPrimary = locale === primaryLanguage;
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
         let totalAbsentForLocale = 0;
@@ -264,11 +275,17 @@ async function generateStatusReport(config) {
                 const primaryState = classifyValue(primaryValue);
                 // Only fall back when the key is genuinely absent from the primary file.
                 // An empty string is intentional (placeholder from extract) — don't hide it.
+                let state = primaryState;
                 if (primaryState === 'absent' && fallbackTranslations) {
                     const fallbackValue = nestedObject.getNestedValue(fallbackTranslations, key, sep);
-                    return classifyValue(fallbackValue);
+                    state = classifyValue(fallbackValue);
                 }
-                return primaryState;
+                // For the primary language the file itself is the source of values, so an
+                // empty placeholder still means the key is present. Only a truly absent
+                // key (used in code, missing from the file) is a problem here.
+                if (isPrimary && state === 'empty')
+                    return 'translated';
+                return state;
             };
             const processedKeys = new Set();
             // Combine AST-extracted keys with nested-reference keys discovered in
@@ -365,13 +382,19 @@ async function generateStatusReport(config) {
             totalAbsentForLocale += absentInNs;
             totalKeysForLocale += totalInNs;
         }
-        report.locales.set(locale, {
+        const localeStatus = {
             totalKeys: totalKeysForLocale,
             totalTranslated: totalTranslatedForLocale,
             totalEmpty: totalEmptyForLocale,
             totalAbsent: totalAbsentForLocale,
             namespaces,
-        });
+        };
+        if (isPrimary) {
+            report.primary = localeStatus;
+        }
+        else {
+            report.locales.set(locale, localeStatus);
+        }
     }
     return report;
 }
@@ -419,15 +442,12 @@ async function displayStatusReport(report, config, options) {
  *   ✗  red    — absent from file entirely (structural problem)
  */
 async function displayDetailedLocaleReport(report, config, locale, namespaceFilter, hideTranslated) {
-    if (locale === config.extract.primaryLanguage) {
-        console.log(node_util.styleText('yellow', `Locale "${locale}" is the primary language. All keys are considered present.`));
-        return;
-    }
     if (!config.locales.includes(locale)) {
         console.error(node_util.styleText('red', `Error: Locale "${locale}" is not defined in your configuration.`));
         return;
     }
-    const localeData = report.locales.get(locale);
+    const isPrimary = locale === config.extract.primaryLanguage;
+    const localeData = isPrimary ? report.primary : report.locales.get(locale);
     if (!localeData) {
         console.error(node_util.styleText('red', `Error: Locale "${locale}" is not a valid secondary language.`));
         return;
@@ -465,8 +485,16 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
     }
     const missingCount = totalKeysForLocale - localeData.totalTranslated;
     if (missingCount > 0) {
-        const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
-        console.log(node_util.styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
+        if (isPrimary) {
+            console.log(node_util.styleText(['red', 'bold'], `\nSummary: Found ${missingCount} key(s) used in code but absent from the "${locale}" translation files. Run "i18next-cli extract" to add them.`));
+        }
+        else {
+            const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
+            console.log(node_util.styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
+        }
+    }
+    else if (isPrimary) {
+        console.log(node_util.styleText(['green', 'bold'], `\nSummary: 🎉 All keys used in code are present in the "${locale}" translation files.`));
     }
     else {
         console.log(node_util.styleText(['green', 'bold'], `\nSummary: 🎉 All keys are translated for "${locale}".`));
@@ -501,6 +529,11 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
             console.log(`- ${locale}: ${bar} ${percentage}% (${nsLocaleData.translatedKeys}/${nsLocaleData.totalKeys} keys)${suffix}`);
         }
     }
+    const primaryNsData = report.primary?.namespaces.get(namespace);
+    if (primaryNsData && primaryNsData.absentKeys > 0) {
+        const { primaryLanguage } = config.extract;
+        console.log(node_util.styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${primaryNsData.absentKeys} key(s) that are used in code.`));
+    }
     await printLocizeFunnel();
 }
 /**
@@ -531,6 +564,10 @@ async function displayOverallSummaryReport(report, config) {
         const suffix = breakdown ? `  — ${breakdown}` : '';
         console.log(`- ${locale}: ${bar} ${percentage}% (${localeData.totalTranslated}/${localeData.totalKeys} keys)${suffix}`);
     }
+    if (report.primary && report.primary.totalAbsent > 0) {
+        console.log(node_util.styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${report.primary.totalAbsent} key(s) that are used in code.`));
+        console.log(node_util.styleText('red', `  Run "i18next-cli status ${primaryLanguage}" for details, or "i18next-cli extract" to add them.`));
+    }
     await printLocizeFunnel();
 }
 /**

package/dist/esm/cli.js

@@ -30,7 +30,7 @@ const program = new Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.59.1'); // This string is replaced with the actual version at build time by rollup
+    .version('1.61.0'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program

package/dist/esm/extractor/parsers/ast-utils.js

@@ -101,6 +101,172 @@ function lineColumnFromOffset(code, offset) {
         column: lines[lines.length - 1].length
     };
 }
+// ─── Byte → char offset helpers ────────────────────────────────────────────
+/**
+ * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
+ * indices (UTF-16 code-unit positions).
+ *
+ * SWC internally represents source as UTF-8 and reports AST spans as byte
+ * offsets into that representation.  MagicString and all JavaScript String
+ * methods operate on UTF-16 code-unit indices.  For files that contain only
+ * ASCII characters the two coincide, so this function returns `null` as a
+ * fast path.  For files with multi-byte characters (emoji, accented letters,
+ * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
+ */
+function buildByteToCharMap(content) {
+    // Fast path: pure ASCII means byte offset ≡ char index
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(content))
+        return null;
+    const map = [];
+    let byteIdx = 0;
+    for (let charIdx = 0; charIdx < content.length;) {
+        const cp = content.codePointAt(charIdx);
+        const byteLen = cp <= 0x7F ? 1 : cp <= 0x7FF ? 2 : cp <= 0xFFFF ? 3 : 4;
+        const charLen = cp > 0xFFFF ? 2 : 1; // surrogate pair
+        // Every byte belonging to this character maps to the same char index
+        for (let b = 0; b < byteLen; b++) {
+            map[byteIdx + b] = charIdx;
+        }
+        byteIdx += byteLen;
+        charIdx += charLen;
+    }
+    // Sentinel so that span.end (one-past-the-last-byte) resolves correctly
+    map[byteIdx] = content.length;
+    return map;
+}
+/**
+ * Recursively converts every `span.start` / `span.end` in an SWC AST from
+ * UTF-8 byte offsets to JavaScript string character indices using the
+ * pre-built lookup table.
+ */
+function convertSpansToCharIndices(node, byteToChar) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (node.span && typeof node.span.start === 'number') {
+        const charStart = byteToChar[node.span.start];
+        const charEnd = byteToChar[node.span.end];
+        if (charStart !== undefined && charEnd !== undefined) {
+            node.span = { ...node.span, start: charStart, end: charEnd };
+        }
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'span')
+            continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) {
+                if (item && typeof item === 'object') {
+                    convertSpansToCharIndices(item, byteToChar);
+                }
+            }
+        }
+        else if (child && typeof child === 'object') {
+            convertSpansToCharIndices(child, byteToChar);
+        }
+    }
+}
+// ─── Ignore-comment helpers ──────────────────────────────────────────────────
+/**
+ * Matches the shared ignore directive used by both the instrumenter and the
+ * linter. The optional `-next-line` suffix is captured in group 1:
+ *
+ *   i18next-instrument-ignore-next-line  → suppress only the single next line
+ *   i18next-instrument-ignore            → suppress the whole next JSX element
+ *
+ * Works in line-comment (`// ...`) and block-comment form, including the JSX
+ * `{ /* ... * / }` form.
+ */
+const IGNORE_DIRECTIVE_RE = /i18next-instrument-ignore(-next-line)?/;
+/**
+ * Scans `code` for ignore-directive comments and returns a Set of 1-based line
+ * numbers whose issues/strings should be suppressed.
+ *
+ * A directive on line `D` targets the following line `D + 1`. The behaviour
+ * depends on the directive variant:
+ *
+ *   - `i18next-instrument-ignore-next-line` suppresses only line `D + 1`.
+ *   - `i18next-instrument-ignore` suppresses the **entire JSX element** that
+ *     begins on line `D + 1` — i.e. every line from its opening tag through its
+ *     closing tag, including nested children. This makes a single directive
+ *     cover multi-line elements (e.g. `<div … css={…}>…</div>`) and elements
+ *     with nested children, instead of just the one physical line after it.
+ *
+ * When no AST node begins on the targeted line (e.g. the next line is a plain
+ * `t()` call rather than a JSX element), block scope falls back to suppressing
+ * the single targeted line, preserving the original line-based behaviour.
+ *
+ * `ast` spans must already be normalised to file-relative character indices
+ * (see {@link normalizeASTSpans} / {@link convertSpansToCharIndices}).
+ */
+function collectIgnoredLineRanges(ast, code) {
+    const ignored = new Set();
+    const lines = code.split('\n');
+    // 1-based target lines, split by directive variant.
+    const blockTargets = new Set();
+    const lineTargets = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const match = IGNORE_DIRECTIVE_RE.exec(lines[i]);
+        if (!match)
+            continue;
+        const target = i + 2; // directive on line i+1 (1-based) → target line i+2
+        if (match[1])
+            lineTargets.add(target); // `-next-line` variant
+        else
+            blockTargets.add(target);
+    }
+    if (blockTargets.size === 0 && lineTargets.size === 0)
+        return ignored;
+    // Always suppress the directly targeted line. For `-next-line` this is the
+    // whole effect; for block directives it is the fallback when no element is
+    // found, and otherwise the start of the suppressed range.
+    for (const target of lineTargets)
+        ignored.add(target);
+    for (const target of blockTargets)
+        ignored.add(target);
+    if (blockTargets.size === 0)
+        return ignored;
+    // For block directives, find the widest AST node that begins on the targeted
+    // line and expand suppression to cover its full line span. Multiple nodes can
+    // start on the same line (e.g. a JSXElement and its JSXOpeningElement); taking
+    // the largest end line picks the outermost element.
+    const widestEndLineByStartLine = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (node.span && typeof node.span.start === 'number') {
+            const start = lineColumnFromOffset(code, node.span.start);
+            if (start && blockTargets.has(start.line)) {
+                const end = lineColumnFromOffset(code, node.span.end);
+                if (end) {
+                    const prev = widestEndLineByStartLine.get(start.line);
+                    if (prev === undefined || end.line > prev) {
+                        widestEndLineByStartLine.set(start.line, end.line);
+                    }
+                }
+            }
+        }
+        for (const key of Object.keys(node)) {
+            if (key === 'span')
+                continue;
+            const child = node[key];
+            if (Array.isArray(child)) {
+                for (const item of child)
+                    visit(item);
+            }
+            else if (child && typeof child === 'object') {
+                visit(child);
+            }
+        }
+    };
+    visit(ast);
+    for (const target of blockTargets) {
+        const endLine = widestEndLineByStartLine.get(target) ?? target;
+        for (let line = target; line <= endLine; line++)
+            ignored.add(line);
+    }
+    return ignored;
+}
 /**
  * Finds and returns the full property node (KeyValueProperty) for the given
  * property name from an ObjectExpression.
@@ -187,4 +353,4 @@ function getObjectPropValue(object, propName, identifierResolver) {
     return undefined;
 }
 
-export { findFirstTokenIndex, getObjectPropValue, getObjectPropValueExpression, getObjectProperty, isSimpleTemplateLiteral, lineColumnFromOffset, normalizeASTSpans };
+export { buildByteToCharMap, collectIgnoredLineRanges, convertSpansToCharIndices, findFirstTokenIndex, getObjectPropValue, getObjectPropValueExpression, getObjectProperty, isSimpleTemplateLiteral, lineColumnFromOffset, normalizeASTSpans };

package/dist/esm/instrumenter/core/instrumenter.js

@@ -10,7 +10,7 @@ import { createKeyRegistry, generateKeyFromContent } from './key-generator.js';
 import { createSpinnerLike } from '../../utils/wrap-ora.js';
 import { ConsoleLogger } from '../../utils/logger.js';
 import { ignoredAttributeSet } from '../../utils/jsx-attributes.js';
-import { findFirstTokenIndex, normalizeASTSpans } from '../../extractor/parsers/ast-utils.js';
+import { findFirstTokenIndex, normalizeASTSpans, buildByteToCharMap, convertSpansToCharIndices, collectIgnoredLineRanges } from '../../extractor/parsers/ast-utils.js';
 import { getOutputPath } from '../../utils/file-utils.js';
 
 /**
@@ -294,11 +294,13 @@ async function scanFileForCandidates(content, file, config) {
         }
         // Filter out candidates suppressed by ignore-comment directives.
         // Supported comments (line or block):
-        //   // i18next-instrument-ignore-next-line
-        //   // i18next-instrument-ignore
+        //   // i18next-instrument-ignore-next-line  → suppress the single next line
+        //   // i18next-instrument-ignore            → suppress the whole next JSX element
         //   /* i18next-instrument-ignore-next-line */
         //   /* i18next-instrument-ignore */
-        const ignoredLines = collectIgnoredLines(content);
+        // AST spans were normalised to char indices above, so the shared helper can
+        // resolve element line ranges directly.
+        const ignoredLines = collectIgnoredLineRanges(ast, content);
         if (ignoredLines.size > 0) {
             const keep = [];
             for (const c of candidates) {
@@ -316,32 +318,6 @@ async function scanFileForCandidates(content, file, config) {
     }
     return { candidates, components, languageChangeSites };
 }
-// ─── Ignore-comment helpers ──────────────────────────────────────────────────
-/**
- * Regex that matches a directive comment requesting the instrumenter to skip
- * the **next** line. Works with both line comments (`// ...`) and block
- * comments. The supported directives are:
- *
- *   i18next-instrument-ignore-next-line
- *   i18next-instrument-ignore
- */
-const IGNORE_RE = /i18next-instrument-ignore(?:-next-line)?/;
-/**
- * Scans `content` for ignore-directive comments and returns a Set of 1-based
- * line numbers whose strings should be excluded from instrumentation.
- */
-function collectIgnoredLines(content) {
-    const ignored = new Set();
-    const lines = content.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        if (IGNORE_RE.test(lines[i])) {
-            // Directive on line i → suppress the *following* line (i + 1)
-            // We store 1-based line numbers, so the suppressed line is i + 2
-            ignored.add(i + 2);
-        }
-    }
-    return ignored;
-}
 /**
  * Returns the 1-based line number for a character offset.
  */
@@ -1962,70 +1938,5 @@ async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugin
     }
     return candidates;
 }
-// ─── Byte → char offset helpers ────────────────────────────────────────────
-/**
- * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
- * indices (UTF-16 code-unit positions).
- *
- * SWC internally represents source as UTF-8 and reports AST spans as byte
- * offsets into that representation.  MagicString and all JavaScript String
- * methods operate on UTF-16 code-unit indices.  For files that contain only
- * ASCII characters the two coincide, so this function returns `null` as a
- * fast path.  For files with multi-byte characters (emoji, accented letters,
- * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
- */
-function buildByteToCharMap(content) {
-    // Fast path: pure ASCII means byte offset ≡ char index
-    // eslint-disable-next-line no-control-regex
-    if (!/[^\x00-\x7F]/.test(content))
-        return null;
-    const map = [];
-    let byteIdx = 0;
-    for (let charIdx = 0; charIdx < content.length;) {
-        const cp = content.codePointAt(charIdx);
-        const byteLen = cp <= 0x7F ? 1 : cp <= 0x7FF ? 2 : cp <= 0xFFFF ? 3 : 4;
-        const charLen = cp > 0xFFFF ? 2 : 1; // surrogate pair
-        // Every byte belonging to this character maps to the same char index
-        for (let b = 0; b < byteLen; b++) {
-            map[byteIdx + b] = charIdx;
-        }
-        byteIdx += byteLen;
-        charIdx += charLen;
-    }
-    // Sentinel so that span.end (one-past-the-last-byte) resolves correctly
-    map[byteIdx] = content.length;
-    return map;
-}
-/**
- * Recursively converts every `span.start` / `span.end` in an SWC AST from
- * UTF-8 byte offsets to JavaScript string character indices using the
- * pre-built lookup table.
- */
-function convertSpansToCharIndices(node, byteToChar) {
-    if (!node || typeof node !== 'object')
-        return;
-    if (node.span && typeof node.span.start === 'number') {
-        const charStart = byteToChar[node.span.start];
-        const charEnd = byteToChar[node.span.end];
-        if (charStart !== undefined && charEnd !== undefined) {
-            node.span = { ...node.span, start: charStart, end: charEnd };
-        }
-    }
-    for (const key of Object.keys(node)) {
-        if (key === 'span')
-            continue;
-        const child = node[key];
-        if (Array.isArray(child)) {
-            for (const item of child) {
-                if (item && typeof item === 'object') {
-                    convertSpansToCharIndices(item, byteToChar);
-                }
-            }
-        }
-        else if (child && typeof child === 'object') {
-            convertSpansToCharIndices(child, byteToChar);
-        }
-    }
-}
 
 export { runInstrumenter, writeExtractedKeys };

package/dist/esm/linter.js

@@ -7,6 +7,7 @@ import { styleText } from 'node:util';
 import { ConsoleLogger } from './utils/logger.js';
 import { createSpinnerLike } from './utils/wrap-ora.js';
 import { acceptedTags, translatableAttributes, ignoredTags, ignoredAttributeLowerSet } from './utils/jsx-attributes.js';
+import { findFirstTokenIndex, normalizeASTSpans, buildByteToCharMap, convertSpansToCharIndices, collectIgnoredLineRanges } from './extractor/parsers/ast-utils.js';
 
 /**
  * Loads all translation values from the primary locale's JSON files and returns
@@ -99,34 +100,6 @@ 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 = [];
@@ -401,14 +374,30 @@ class Linter extends EventEmitter {
                         continue;
                     }
                 }
+                // Normalise AST spans to file-relative character indices so the ignore
+                // directive can resolve the line range of the JSX element it precedes.
+                // (findHardcodedStrings/lintInterpolationParams locate issues via text
+                // search and don't read spans, so this only affects ignore handling.)
+                try {
+                    const spanBase = ast.span.start - findFirstTokenIndex(code);
+                    normalizeASTSpans(ast, spanBase);
+                    const byteToChar = buildByteToCharMap(code);
+                    if (byteToChar)
+                        convertSpansToCharIndices(ast, byteToChar);
+                }
+                catch {
+                    // If span normalisation fails for any reason, fall back to text-based
+                    // issue detection without block-scoped ignore support.
+                }
                 // Collect hardcoded string issues
                 const hardcodedStrings = findHardcodedStrings(ast, code, config);
                 // 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);
+                //   i18next-instrument-ignore-next-line → suppresses the single next line
+                //   i18next-instrument-ignore           → suppresses the whole next JSX element
+                const ignoredLines = collectIgnoredLineRanges(ast, code);
                 if (ignoredLines.size > 0) {
                     allIssues = allIssues.filter(issue => !ignoredLines.has(issue.line));
                 }

package/dist/esm/status.js

@@ -54,6 +54,11 @@ async function runStatus(config, options = {}) {
                 break;
             }
         }
+        // The primary language fails the check only on absent keys (used in code but
+        // missing from the translation file); empty placeholders are tolerated.
+        if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
+            hasMissing = true;
+        }
         if (hasMissing) {
             spinner.fail('Error: Incomplete translations detected.');
             process.exit(1);
@@ -201,7 +206,13 @@ async function generateStatusReport(config) {
         if (nestedRefKeys.length > 0)
             nestedReferenceKeysByNs.set(ns, nestedRefKeys);
     }
-    for (const locale of secondaryLanguages) {
+    // The primary language is checked first so that keys used in code but absent
+    // from the primary translation file (e.g. a typo, or `extract` never run) are
+    // surfaced as well. For the primary, an empty value is a deliberate
+    // placeholder and counts as present — only truly absent keys are flagged.
+    const localesToCheck = [primaryLanguage, ...secondaryLanguages.filter((l) => l !== primaryLanguage)];
+    for (const locale of localesToCheck) {
+        const isPrimary = locale === primaryLanguage;
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
         let totalAbsentForLocale = 0;
@@ -262,11 +273,17 @@ async function generateStatusReport(config) {
                 const primaryState = classifyValue(primaryValue);
                 // Only fall back when the key is genuinely absent from the primary file.
                 // An empty string is intentional (placeholder from extract) — don't hide it.
+                let state = primaryState;
                 if (primaryState === 'absent' && fallbackTranslations) {
                     const fallbackValue = getNestedValue(fallbackTranslations, key, sep);
-                    return classifyValue(fallbackValue);
+                    state = classifyValue(fallbackValue);
                 }
-                return primaryState;
+                // For the primary language the file itself is the source of values, so an
+                // empty placeholder still means the key is present. Only a truly absent
+                // key (used in code, missing from the file) is a problem here.
+                if (isPrimary && state === 'empty')
+                    return 'translated';
+                return state;
             };
             const processedKeys = new Set();
             // Combine AST-extracted keys with nested-reference keys discovered in
@@ -363,13 +380,19 @@ async function generateStatusReport(config) {
             totalAbsentForLocale += absentInNs;
             totalKeysForLocale += totalInNs;
         }
-        report.locales.set(locale, {
+        const localeStatus = {
             totalKeys: totalKeysForLocale,
             totalTranslated: totalTranslatedForLocale,
             totalEmpty: totalEmptyForLocale,
             totalAbsent: totalAbsentForLocale,
             namespaces,
-        });
+        };
+        if (isPrimary) {
+            report.primary = localeStatus;
+        }
+        else {
+            report.locales.set(locale, localeStatus);
+        }
     }
     return report;
 }
@@ -417,15 +440,12 @@ async function displayStatusReport(report, config, options) {
  *   ✗  red    — absent from file entirely (structural problem)
  */
 async function displayDetailedLocaleReport(report, config, locale, namespaceFilter, hideTranslated) {
-    if (locale === config.extract.primaryLanguage) {
-        console.log(styleText('yellow', `Locale "${locale}" is the primary language. All keys are considered present.`));
-        return;
-    }
     if (!config.locales.includes(locale)) {
         console.error(styleText('red', `Error: Locale "${locale}" is not defined in your configuration.`));
         return;
     }
-    const localeData = report.locales.get(locale);
+    const isPrimary = locale === config.extract.primaryLanguage;
+    const localeData = isPrimary ? report.primary : report.locales.get(locale);
     if (!localeData) {
         console.error(styleText('red', `Error: Locale "${locale}" is not a valid secondary language.`));
         return;
@@ -463,8 +483,16 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
     }
     const missingCount = totalKeysForLocale - localeData.totalTranslated;
     if (missingCount > 0) {
-        const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
-        console.log(styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
+        if (isPrimary) {
+            console.log(styleText(['red', 'bold'], `\nSummary: Found ${missingCount} key(s) used in code but absent from the "${locale}" translation files. Run "i18next-cli extract" to add them.`));
+        }
+        else {
+            const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
+            console.log(styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
+        }
+    }
+    else if (isPrimary) {
+        console.log(styleText(['green', 'bold'], `\nSummary: 🎉 All keys used in code are present in the "${locale}" translation files.`));
     }
     else {
         console.log(styleText(['green', 'bold'], `\nSummary: 🎉 All keys are translated for "${locale}".`));
@@ -499,6 +527,11 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
             console.log(`- ${locale}: ${bar} ${percentage}% (${nsLocaleData.translatedKeys}/${nsLocaleData.totalKeys} keys)${suffix}`);
         }
     }
+    const primaryNsData = report.primary?.namespaces.get(namespace);
+    if (primaryNsData && primaryNsData.absentKeys > 0) {
+        const { primaryLanguage } = config.extract;
+        console.log(styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${primaryNsData.absentKeys} key(s) that are used in code.`));
+    }
     await printLocizeFunnel();
 }
 /**
@@ -529,6 +562,10 @@ async function displayOverallSummaryReport(report, config) {
         const suffix = breakdown ? `  — ${breakdown}` : '';
         console.log(`- ${locale}: ${bar} ${percentage}% (${localeData.totalTranslated}/${localeData.totalKeys} keys)${suffix}`);
     }
+    if (report.primary && report.primary.totalAbsent > 0) {
+        console.log(styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${report.primary.totalAbsent} key(s) that are used in code.`));
+        console.log(styleText('red', `  Run "i18next-cli status ${primaryLanguage}" for details, or "i18next-cli extract" to add them.`));
+    }
     await printLocizeFunnel();
 }
 /**

package/package.json

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

package/types/extractor/parsers/ast-utils.d.ts

@@ -36,6 +36,46 @@ export declare function lineColumnFromOffset(code: string, offset: number): {
     line: number;
     column: number;
 } | undefined;
+/**
+ * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
+ * indices (UTF-16 code-unit positions).
+ *
+ * SWC internally represents source as UTF-8 and reports AST spans as byte
+ * offsets into that representation.  MagicString and all JavaScript String
+ * methods operate on UTF-16 code-unit indices.  For files that contain only
+ * ASCII characters the two coincide, so this function returns `null` as a
+ * fast path.  For files with multi-byte characters (emoji, accented letters,
+ * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
+ */
+export declare function buildByteToCharMap(content: string): number[] | null;
+/**
+ * Recursively converts every `span.start` / `span.end` in an SWC AST from
+ * UTF-8 byte offsets to JavaScript string character indices using the
+ * pre-built lookup table.
+ */
+export declare function convertSpansToCharIndices(node: any, byteToChar: number[]): void;
+/**
+ * Scans `code` for ignore-directive comments and returns a Set of 1-based line
+ * numbers whose issues/strings should be suppressed.
+ *
+ * A directive on line `D` targets the following line `D + 1`. The behaviour
+ * depends on the directive variant:
+ *
+ *   - `i18next-instrument-ignore-next-line` suppresses only line `D + 1`.
+ *   - `i18next-instrument-ignore` suppresses the **entire JSX element** that
+ *     begins on line `D + 1` — i.e. every line from its opening tag through its
+ *     closing tag, including nested children. This makes a single directive
+ *     cover multi-line elements (e.g. `<div … css={…}>…</div>`) and elements
+ *     with nested children, instead of just the one physical line after it.
+ *
+ * When no AST node begins on the targeted line (e.g. the next line is a plain
+ * `t()` call rather than a JSX element), block scope falls back to suppressing
+ * the single targeted line, preserving the original line-based behaviour.
+ *
+ * `ast` spans must already be normalised to file-relative character indices
+ * (see {@link normalizeASTSpans} / {@link convertSpansToCharIndices}).
+ */
+export declare function collectIgnoredLineRanges(ast: any, code: string): Set<number>;
 /**
  * Finds and returns the full property node (KeyValueProperty) for the given
  * property name from an ObjectExpression.

package/types/extractor/parsers/ast-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-utils.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/ast-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE1F;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA2BzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0BhE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAQhH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,qDAU5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAKhH;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAE1E;AAED,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;AAEjF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAkB9J"}
+{"version":3,"file":"ast-utils.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/ast-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE1F;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA2BzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0BhE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAQhH;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CA0BpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAwBhF;AAgBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CA4D7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,qDAU5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAKhH;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAE1E;AAED,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;AAEjF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAkB9J"}

package/types/instrumenter/core/instrumenter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrumenter.d.ts","sourceRoot":"","sources":["../../../src/instrumenter/core/instrumenter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,eAAe,EAA6B,sBAAsB,EAAiE,MAAM,gBAAgB,CAAA;AAU1N;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAoNjC;AA4wDD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf"}
+{"version":3,"file":"instrumenter.d.ts","sourceRoot":"","sources":["../../../src/instrumenter/core/instrumenter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,eAAe,EAA6B,sBAAsB,EAAiE,MAAM,gBAAgB,CAAA;AAU1N;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAoNjC;AAivDD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/types/linter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../src/linter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAK1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAA;AA8SpG,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE;QAAC;YACT,OAAO,EAAE,MAAM,CAAC;SACjB;KAAC,CAAC;IACH,IAAI,EAAE;QAAC;YACL,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;SACpC;KAAC,CAAC;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAAiD,CAAA;AAC7F,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAAqD,CAAA;AAKvG,qBAAa,MAAO,SAAQ,YAAY,CAAC,cAAc,CAAC;IACtD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAQ;gBAET,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAE,MAA4B;IAM/E,SAAS,CAAE,KAAK,EAAE,OAAO;IAanB,GAAG;;;;;;;IAmHT,OAAO,CAAC,uBAAuB;YAOjB,qBAAqB;IAWnC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,0BAA0B;YAUpB,qBAAqB;YAgBrB,uBAAuB;CAgBtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB;;;;;;GAE5D;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,iBAkCnD"}
+{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../src/linter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAM1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAA;AA+QpG,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE;QAAC;YACT,OAAO,EAAE,MAAM,CAAC;SACjB;KAAC,CAAC;IACH,IAAI,EAAE;QAAC;YACL,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;SACpC;KAAC,CAAC;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAAiD,CAAA;AAC7F,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAAqD,CAAA;AAKvG,qBAAa,MAAO,SAAQ,YAAY,CAAC,cAAc,CAAC;IACtD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAQ;gBAET,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAE,MAA4B;IAM/E,SAAS,CAAE,KAAK,EAAE,OAAO;IAanB,GAAG;;;;;;;IAkIT,OAAO,CAAC,uBAAuB;YAOjB,qBAAqB;IAWnC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,0BAA0B;YAUpB,qBAAqB;YAgBrB,uBAAuB;CAgBtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB;;;;;;GAE5D;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,iBAkCnD"}

package/types/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAgB,MAAM,YAAY,CAAA;AAOpE;;GAEG;AACH,UAAU,aAAa;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAqDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,GAAE,aAAkB,iBAuBzF"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAgB,MAAM,YAAY,CAAA;AAOpE;;GAEG;AACH,UAAU,aAAa;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAiED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,GAAE,aAAkB,iBA4BzF"}