react-i18next-scanner 0.1.1 → 0.1.3

package/README.md

@@ -11,7 +11,7 @@ CLI tool to scan React projects for missing and unused `react-i18next` translati
 - Sync missing keys into translation JSON files
 - Remove unused keys from translation JSON files
 - Sort translation JSON files alphabetically
-- Works with `.js`, `.jsx`, `.ts`, `.tsx`
+- Detect dynamic translation usages and write them into a separate report
 
 ---
 
@@ -37,6 +37,8 @@ Create one of these config files in your project root:
 - `i18n-scanner.config.cjs`
 - `i18n-scanner.config.mjs`
 
+> `.ts` config is not supported yet.
+
 Example:
 
 ```js
@@ -112,6 +114,20 @@ If `true`, unused keys will be removed from translation JSON files.
 
 ## Commands
 
+### Initialize config
+
+```bash
+npx react-i18next-scanner init
+```
+
+This command creates a config file automatically and lets you choose:
+
+- `.js`
+- `.mjs`
+- `.cjs`
+
+---
+
 ### Scan project
 
 ```bash
@@ -130,6 +146,7 @@ What it does:
 - extracts translation keys
 - compares them with translation JSON files
 - writes unused translation reports
+- writes dynamic translation usage reports
 - optionally syncs missing keys
 - optionally removes unused keys
 
@@ -178,7 +195,40 @@ These files contain only unused translations, so you can review them safely befo
 
 ---
 
-## Supported Patterns
+## Dynamic Translation Report
+
+If the scanner finds dynamic translation usage such as:
+
+```ts
+t(getDescription());
+t(labelKey);
+t(transaction.descriptionKey);
+```
+
+it creates a report file:
+
+```bash
+reports-dynamic/dynamic-translation-usages.json
+```
+
+Example structure:
+
+```json
+{
+  "src/views/Account/BalancesTransactionsPage/PaymentDescription.tsx": [
+    {
+      "namespaces": ["accountInformation"],
+      "expression": "getDescription()",
+      "reason": "Object-based non-literal translation key",
+      "suggestion": "Translation key may come from imported object(s) or helper functions. Manual or deeper analysis may be required."
+    }
+  ]
+}
+```
+
+---
+
+## Supported Translation Patterns
 
 The scanner currently detects translation keys used with:
 
@@ -187,6 +237,31 @@ The scanner currently detects translation keys used with:
 - `<Trans i18nKey="key" />`
 - `useTranslation("namespace")`
 
+It can also report dynamic usages where translation keys are not passed directly as string literals.
+
+---
+
+## Supported Files
+
+### Source files
+
+The scanner can scan:
+
+- `.js`
+- `.jsx`
+- `.ts`
+- `.tsx`
+
+### Config files
+
+The scanner currently supports:
+
+- `.js`
+- `.cjs`
+- `.mjs`
+
+> `.ts` config is not supported yet.
+
 ---
 
 ## Example Workflow
@@ -252,9 +327,10 @@ npx react-i18next-scanner scan
 
 ## Notes
 
-- Use `syncMissing` carefully if you do not want automatic changes in translation files.
-- Use `removeUnused` only after reviewing generated unused translation reports.
-- Translation paths are resolved relative to the config file location.
+- `syncMissing` does not translate values automatically. It only adds missing keys with empty values.
+- `removeUnused` should be used carefully after reviewing unused translation reports.
+- Dynamic translation usages are written into a separate report and are not automatically resolved.
+- Config paths are resolved relative to the config file location.
 
 ---
 

package/dist/config/loadConfig.js

@@ -41,6 +41,9 @@ function validateConfig(config) {
     if (cfg.syncMissing !== undefined && typeof cfg.syncMissing !== "boolean") {
         throw new Error("syncMissing must be a boolean.");
     }
+    if (cfg.sortJson !== undefined && typeof cfg.sortJson !== "boolean") {
+        throw new Error("sortJson must be a boolean.");
+    }
     if (cfg.outputDir !== undefined && typeof cfg.outputDir !== "string") {
         throw new Error("outputDir must be a string.");
     }
@@ -52,6 +55,7 @@ function normalizeConfig(config, baseDir) {
         sortJsonFiles: config.sortJsonFiles?.map((p) => path.resolve(baseDir, p)),
         removeUnused: config.removeUnused ?? false,
         syncMissing: config.syncMissing ?? false,
+        sortJson: config.sortJson ?? false,
         outputDir: path.resolve(baseDir, config.outputDir ?? "unused-translations"),
     };
 }

package/dist/core/actions/removeUnusedTranslations.js

@@ -1,7 +1,7 @@
 import fs from "fs/promises";
 import { removeKey } from "../utils/removeKey.js";
 import { sortObject } from "../utils/sortObject.js";
-export async function removeUnusedTranslations(result, jsonFiles) {
+export async function removeUnusedTranslations(result, jsonFiles, sortJson) {
     const { unusedKeysByFile } = result;
     for (const file of jsonFiles) {
         const unusedKeys = unusedKeysByFile[file.filePath] ?? [];
@@ -19,7 +19,7 @@ export async function removeUnusedTranslations(result, jsonFiles) {
         if (!updated) {
             continue;
         }
-        const sorted = sortObject(file.data);
+        const sorted = sortJson ? sortObject(file.data) : file.data;
         file.data = sorted;
         await fs.writeFile(file.filePath, JSON.stringify(sorted, null, 2), "utf-8");
         console.log(`\n✅ Unused keys removed: ${file.filePath}`);

package/dist/core/actions/syncMissingTranslations.js

@@ -2,7 +2,7 @@ import fs from "fs/promises";
 import { addKey } from "../utils/addKey.js";
 import { sortObject } from "../utils/sortObject.js";
 import { isValidTranslationKey } from "../utils/isValidTranslationKey.js";
-export async function syncMissingTranslations(result, jsonFiles) {
+export async function syncMissingTranslations(result, jsonFiles, sortJson) {
     const { missingKeysByFile } = result;
     for (const file of jsonFiles) {
         const missingKeys = missingKeysByFile[file.filePath] ?? [];
@@ -23,7 +23,7 @@ export async function syncMissingTranslations(result, jsonFiles) {
         if (!updated) {
             continue;
         }
-        const sorted = sortObject(file.data);
+        const sorted = sortJson ? sortObject(file.data) : file.data;
         file.data = sorted;
         await fs.writeFile(file.filePath, JSON.stringify(sorted, null, 2), "utf-8");
         console.log(`\n✅ Missing keys synced: ${file.filePath}`);

package/dist/core/actions/writeDynamicTranslationReport.js

@@ -0,0 +1,14 @@
+import fs from "fs/promises";
+import path from "path";
+import { sortObject } from "../utils/sortObject.js";
+const DEFAULT_DYNAMIC_REPORT_DIR = path.resolve(process.cwd(), "reports-dynamic");
+export async function writeDynamicTranslationReport(report, outputDir = DEFAULT_DYNAMIC_REPORT_DIR) {
+    if (Object.keys(report).length === 0) {
+        return;
+    }
+    await fs.mkdir(outputDir, { recursive: true });
+    const reportPath = path.join(outputDir, "dynamic-translation-usages.json");
+    const sortedReport = sortObject(report);
+    await fs.writeFile(reportPath, `${JSON.stringify(sortedReport, null, 2)}\n`, "utf-8");
+    console.log(`📝 Dynamic translation report created: ${reportPath}`);
+}

package/dist/core/analysis/detectDynamicTranslationUsages.js

@@ -0,0 +1,180 @@
+import fs from "fs/promises";
+import path from "path";
+import ts from "typescript";
+function getScriptKind(filePath) {
+    if (filePath.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith(".ts"))
+        return ts.ScriptKind.TS;
+    if (filePath.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.JS;
+}
+function createSourceFile(filePath, content) {
+    return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+}
+function extractImportMap(sourceFile) {
+    const imports = new Map();
+    sourceFile.forEachChild((node) => {
+        if (!ts.isImportDeclaration(node))
+            return;
+        if (!node.importClause || !node.moduleSpecifier)
+            return;
+        if (!ts.isStringLiteral(node.moduleSpecifier))
+            return;
+        const modulePath = node.moduleSpecifier.text;
+        const importClause = node.importClause;
+        if (importClause.name) {
+            imports.set(importClause.name.text, modulePath);
+        }
+        if (importClause.namedBindings &&
+            ts.isNamedImports(importClause.namedBindings)) {
+            for (const element of importClause.namedBindings.elements) {
+                const localName = element.name.text;
+                imports.set(localName, modulePath);
+            }
+        }
+    });
+    return imports;
+}
+function extractNamespaces(sourceFile) {
+    const namespaces = new Set();
+    function visit(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "useTranslation") {
+            const firstArg = node.arguments[0];
+            if (!firstArg) {
+                return;
+            }
+            if (ts.isStringLiteral(firstArg) ||
+                ts.isNoSubstitutionTemplateLiteral(firstArg)) {
+                namespaces.add(firstArg.text);
+            }
+            if (ts.isArrayLiteralExpression(firstArg)) {
+                for (const element of firstArg.elements) {
+                    if (ts.isStringLiteral(element) ||
+                        ts.isNoSubstitutionTemplateLiteral(element)) {
+                        namespaces.add(element.text);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return [...namespaces];
+}
+function isTranslationCall(node) {
+    if (ts.isIdentifier(node.expression)) {
+        return node.expression.text === "t";
+    }
+    if (ts.isPropertyAccessExpression(node.expression)) {
+        return node.expression.name.text === "t";
+    }
+    return false;
+}
+function isDirectLiteralTranslationArg(node) {
+    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
+}
+function getExpressionKind(node) {
+    if (ts.isTemplateExpression(node))
+        return "template-literal";
+    if (ts.isIdentifier(node))
+        return "identifier";
+    if (ts.isCallExpression(node))
+        return "function-call";
+    if (ts.isPropertyAccessExpression(node))
+        return "property-access";
+    if (ts.isElementAccessExpression(node))
+        return "element-access";
+    if (ts.isBinaryExpression(node))
+        return "binary-expression";
+    if (ts.isConditionalExpression(node))
+        return "conditional-expression";
+    return "expression";
+}
+function findRelatedImports(expressionText, importMap) {
+    const related = [];
+    for (const [localName, source] of importMap.entries()) {
+        const identifierRegex = new RegExp(`\\b${localName}\\b`);
+        if (identifierRegex.test(expressionText)) {
+            related.push(`${localName} -> ${source}`);
+        }
+    }
+    return related;
+}
+function buildFinding(namespaces, expression, kind, importHints) {
+    let reason = "Non-literal translation key";
+    let suggestion = "Translation key is not passed as a direct string literal. Manual or deeper analysis may be required.";
+    if (kind === "template-literal") {
+        reason = "Template-literal translation key";
+        suggestion =
+            "Translation key uses a template literal with dynamic interpolation. Manual or deeper analysis may be required.";
+    }
+    if (kind === "function-call") {
+        reason = "Function-based translation key";
+        suggestion =
+            "Translation key is returned from a function call. Manual or deeper analysis may be required.";
+    }
+    if (kind === "property-access" ||
+        kind === "element-access" ||
+        kind === "identifier") {
+        reason = "Object-based non-literal translation key";
+        suggestion =
+            "Translation key may come from an object, variable, or imported map. Manual or deeper analysis may be required.";
+    }
+    if (importHints.length > 0) {
+        suggestion += ` Related imports: ${importHints.join(", ")}.`;
+    }
+    return {
+        namespaces,
+        expression,
+        reason,
+        suggestion,
+    };
+}
+function collectDynamicFromExpression(expression, namespaces, importMap, sourceFile, bucket) {
+    if (isDirectLiteralTranslationArg(expression)) {
+        return;
+    }
+    if (ts.isConditionalExpression(expression)) {
+        collectDynamicFromExpression(expression.whenTrue, namespaces, importMap, sourceFile, bucket);
+        collectDynamicFromExpression(expression.whenFalse, namespaces, importMap, sourceFile, bucket);
+        return;
+    }
+    const expressionText = expression.getText(sourceFile).trim();
+    const kind = getExpressionKind(expression);
+    const importHints = findRelatedImports(expressionText, importMap);
+    bucket.push(buildFinding(namespaces, expressionText, kind, importHints));
+}
+export async function detectDynamicTranslationUsages(files) {
+    const report = {};
+    for (const file of files) {
+        const content = await fs.readFile(file, "utf-8");
+        if (!content.includes("t(")) {
+            continue;
+        }
+        const sourceFile = createSourceFile(file, content);
+        const namespaces = extractNamespaces(sourceFile);
+        const importMap = extractImportMap(sourceFile);
+        const findings = [];
+        function visit(node) {
+            if (ts.isCallExpression(node) && isTranslationCall(node)) {
+                const firstArg = node.arguments[0];
+                if (firstArg) {
+                    collectDynamicFromExpression(firstArg, namespaces, importMap, sourceFile, findings);
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        if (findings.length > 0) {
+            const relativePath = path
+                .relative(process.cwd(), file)
+                .replace(/\\/g, "/");
+            report[relativePath] = findings;
+        }
+    }
+    return report;
+}

package/dist/core/runSyncMissing.js

@@ -9,6 +9,6 @@ export async function runSyncMissing(config) {
     const usedKeys = await extractKeysFromFiles(files);
     const jsonData = await loadJsonKeys(config.jsonDir);
     const result = analyzeKeys(usedKeys, jsonData);
-    await syncMissingTranslations(result, jsonData);
+    await syncMissingTranslations(result, jsonData, config.sortJson);
     return result;
 }

package/dist/core/scanner.js

@@ -2,20 +2,24 @@ import { loadJsonKeys } from "./io/jsonLoader.js";
 import { getFiles } from "./io/getFiles.js";
 import { analyzeKeys } from "./analysis/analyzer.js";
 import { extractKeysFromFiles } from "./analysis/extractKeysFromFiles.js";
+import { detectDynamicTranslationUsages } from "./analysis/detectDynamicTranslationUsages.js";
+import { writeDynamicTranslationReport } from "./actions/writeDynamicTranslationReport.js";
 import { syncMissingTranslations } from "./actions/syncMissingTranslations.js";
 import { removeUnusedTranslations } from "./actions/removeUnusedTranslations.js";
 import { writeUnusedTranslationsReport } from "./actions/writeUnusedTranslationsReport.js";
 export async function runScanner(config) {
     const files = await getFiles(config.srcPaths);
+    const dynamicUsages = await detectDynamicTranslationUsages(files);
+    await writeDynamicTranslationReport(dynamicUsages);
     const usedKeys = await extractKeysFromFiles(files);
     const jsonData = await loadJsonKeys(config.jsonDir);
     const result = analyzeKeys(usedKeys, jsonData);
     await writeUnusedTranslationsReport(result, jsonData, config.outputDir);
     if (config.syncMissing) {
-        await syncMissingTranslations(result, jsonData);
+        await syncMissingTranslations(result, jsonData, config.sortJson);
     }
     if (config.removeUnused) {
-        await removeUnusedTranslations(result, jsonData);
+        await removeUnusedTranslations(result, jsonData, config.sortJson);
     }
     return result;
 }

package/package.json

@@ -1,10 +1,8 @@
 {
   "name": "react-i18next-scanner",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI tool to scan React projects for missing and unused react-i18next translation keys",
-  "bin": {
-    "react-i18next-scanner": "./dist/cli/cli.js"
-  },
+  "bin": "./dist/cli/cli.js",
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli/cli.ts",
@@ -26,12 +24,12 @@
   ],
   "devDependencies": {
     "@types/node": "^24.6.2",
-    "tsx": "^4.22.4",
-    "typescript": "^5.9.3"
+    "tsx": "^4.22.4"
   },
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^15.0.0",
-    "fast-glob": "^3.3.3"
+    "fast-glob": "^3.3.3",
+    "typescript": "^6.0.3"
   }
 }