react-i18next-scanner 0.1.0 → 0.1.2

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/cli/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import chalk from "chalk";
+import { runInit } from "../core/runInit.js";
 import { runScanner } from "../core/scanner.js";
 import { sortJsonFiles } from "../core/sortJsonFiles.js";
 import { runSyncMissing } from "../core/runSyncMissing.js";
@@ -13,7 +14,7 @@ function resolveConfigPath(configPath) {
         finalConfigPath = findDefaultConfig() ?? undefined;
     }
     if (!finalConfigPath) {
-        throw new Error(`Config file not found. Create one of: ${POSSIBLE_CONFIGS.join(", ")}`);
+        throw new Error(`Config file not found. Create one of: ${POSSIBLE_CONFIGS.join(", ")}\nRun: react-i18next-scanner init`);
     }
     return finalConfigPath;
 }
@@ -96,4 +97,15 @@ program
         handleCliError(error);
     }
 });
+program
+    .command("init")
+    .description("Create scanner config file automatically")
+    .action(async () => {
+    try {
+        await runInit();
+    }
+    catch (error) {
+        handleCliError(error);
+    }
+});
 await program.parseAsync(process.argv);

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,94 @@
+import fs from "fs/promises";
+import path from "path";
+function extractNamespaces(content) {
+    const namespaces = new Set();
+    const nsRegex = /useTranslation\s*\(\s*(?:\[\s*([^\]]+)\s*\]|['"`]([^'"`]+)['"`])?/g;
+    let match;
+    while ((match = nsRegex.exec(content)) !== null) {
+        if (match[1]) {
+            const values = match[1]
+                .split(",")
+                .map((value) => value.replace(/['"`]/g, "").trim())
+                .filter(Boolean);
+            values.forEach((value) => namespaces.add(value));
+        }
+        if (match[2]) {
+            namespaces.add(match[2]);
+        }
+    }
+    return [...namespaces];
+}
+function extractDynamicTExpressions(content) {
+    const expressions = new Set();
+    const dynamicTRegex = /(^|[^\w$.])t\s*\(\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*(?:\([^()]*\))?)/g;
+    let match;
+    while ((match = dynamicTRegex.exec(content)) !== null) {
+        const expression = match[2]?.trim();
+        if (!expression) {
+            continue;
+        }
+        expressions.add(expression);
+    }
+    return [...expressions];
+}
+function extractImportedIdentifiers(content) {
+    const identifiers = new Set();
+    const importRegex = /import\s+(?:\{([^}]+)\}|([A-Za-z_$][\w$]*))\s+from\s+['"`][^'"`]+['"`]/g;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        if (match[1]) {
+            const namedImports = match[1]
+                .split(",")
+                .map((value) => value.trim())
+                .map((value) => value.split(" as ")[1]?.trim() ?? value.split(" as ")[0]?.trim())
+                .filter(Boolean);
+            namedImports.forEach((value) => identifiers.add(value));
+        }
+        if (match[2]) {
+            identifiers.add(match[2]);
+        }
+    }
+    return [...identifiers];
+}
+function detectObjectBasedUsageHints(content, importedIdentifiers) {
+    const hints = new Set();
+    for (const identifier of importedIdentifiers) {
+        const objectAccessRegex = new RegExp(`${identifier}\\s*\\[[^\\]]+\\]\\.(description|label|title|placeholder|message)|${identifier}\\.[A-Za-z_$][\\w$]*\\.(description|label|title|placeholder|message)`, "g");
+        if (objectAccessRegex.test(content)) {
+            hints.add(identifier);
+        }
+    }
+    return [...hints];
+}
+function buildFinding(namespaces, expression, objectBasedHints) {
+    const isObjectBased = objectBasedHints.length > 0;
+    return {
+        namespaces,
+        expression,
+        reason: isObjectBased
+            ? "Object-based non-literal translation key"
+            : "Non-literal translation key",
+        suggestion: isObjectBased
+            ? `Translation key may come from imported object(s): ${objectBasedHints.join(", ")}. Manual or deeper analysis may be required.`
+            : "Translation key may come from a variable or helper function. Manual or deeper analysis may be required.",
+    };
+}
+export async function detectDynamicTranslationUsages(files) {
+    const report = {};
+    for (const file of files) {
+        const content = await fs.readFile(file, "utf-8");
+        if (!content.includes("useTranslation") || !content.includes("t(")) {
+            continue;
+        }
+        const namespaces = extractNamespaces(content);
+        const expressions = extractDynamicTExpressions(content);
+        if (expressions.length === 0) {
+            continue;
+        }
+        const importedIdentifiers = extractImportedIdentifiers(content);
+        const objectBasedHints = detectObjectBasedUsageHints(content, importedIdentifiers);
+        const relativePath = path.relative(process.cwd(), file).replace(/\\/g, "/");
+        report[relativePath] = expressions.map((expression) => buildFinding(namespaces, expression, objectBasedHints));
+    }
+    return report;
+}

package/dist/core/runInit.js

@@ -0,0 +1,58 @@
+import fs from "fs/promises";
+import path from "path";
+import readline from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+function getConfigFileName(format) {
+    return `i18n-scanner.config.${format}`;
+}
+function getConfigTemplate(format) {
+    const configObject = `{
+  srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"],
+  jsonDir: [
+    "./src/i18n/locales/translations.en.json",
+    "./src/i18n/locales/translations.es.json"
+  ],
+  sortJsonFiles: [
+    "./src/i18n/locales/translations.en.json",
+    "./src/i18n/locales/translations.es.json"
+  ],
+  outputDir: "./unused",
+  syncMissing: false,
+  removeUnused: false
+}`;
+    if (format === "cjs") {
+        return `module.exports = ${configObject};\n`;
+    }
+    return `export default ${configObject};\n`;
+}
+export async function runInit() {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question("Choose config format (js / mjs / cjs): ");
+        const normalized = answer.trim().toLowerCase();
+        if (normalized !== "js" && normalized !== "mjs" && normalized !== "cjs") {
+            throw new Error("Invalid format. Use js, mjs, or cjs.");
+        }
+        const format = normalized;
+        const fileName = getConfigFileName(format);
+        const filePath = path.resolve(process.cwd(), fileName);
+        try {
+            await fs.access(filePath);
+            throw new Error(`${fileName} already exists.`);
+        }
+        catch (error) {
+            if (error instanceof Error && !error.message.includes("already exists")) {
+                // file does not exist, continue
+            }
+            else if (error instanceof Error) {
+                throw error;
+            }
+        }
+        const content = getConfigTemplate(format);
+        await fs.writeFile(filePath, content, "utf-8");
+        console.log(`✅ Created: ${fileName}`);
+    }
+    finally {
+        rl.close();
+    }
+}

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,6 +1,6 @@
 {
   "name": "react-i18next-scanner",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool to scan React projects for missing and unused react-i18next translation keys",
   "bin": {
     "react-i18next-scanner": "./dist/cli/cli.js"