react-i18next-scanner 0.1.7 → 0.1.8

package/README.md

@@ -1,21 +1,23 @@
 # react-i18next-scanner
 
-CLI tool to scan React projects for missing and unused `react-i18next` translation keys.
+CLI tool for React / `react-i18next` projects.
 
-## Features
+It helps you:
 
-- Scan React source files for translation keys
-- Detect missing translation keys
-- Detect unused translation keys
-- Generate separate unused translation reports
-- Sync missing keys into translation JSON files
-- Remove unused keys from translation JSON files
-- Sort translation JSON files alphabetically
-- Detect dynamic translation usages and write them into a separate report
+- find missing translation keys
+- find unused translation keys
+- detect dynamic translation usages
+- protect possibly used dynamic keys from removal
+- generate reports
+- sync missing keys
+- remove definitely unused keys
+- sort translation JSON files
 
 ---
 
-## Installation
+## Quick Start
+
+### 1. Install
 
 ```bash
 npm install -D react-i18next-scanner
@@ -29,150 +31,139 @@ yarn add -D react-i18next-scanner
 
 ---
 
-## Config
-
-Create one of these config files in your project root:
+### 2. Create config
 
-- `i18n-scanner.config.js`
-- `i18n-scanner.config.cjs`
-- `i18n-scanner.config.mjs`
+```bash
+npx react-i18next-scanner init
+```
 
-> `.ts` config is not supported yet.
+This will create a config file for your project.
 
-Example:
+Supported config formats:
 
-```js
-export default {
-  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,
-};
+```txt
+i18n-scanner.config.js
+i18n-scanner.config.cjs
+i18n-scanner.config.mjs
 ```
 
----
-
-## Config Options
+> `.ts` config is not supported yet.
 
-### `srcPaths`
+---
 
-Array of source file glob patterns to scan.
+### 3. Run scan
 
-```js
-srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"];
+```bash
+npx react-i18next-scanner scan
 ```
 
-### `jsonDir`
+The scanner will check your source files and translation JSON files.
 
-Array of translation JSON files to analyze.
+Reports will be created inside:
 
-```js
-jsonDir: [
-  "./src/i18n/locales/translations.en.json",
-  "./src/i18n/locales/translations.es.json",
-];
+```txt
+reports/
 ```
 
-### `sortJsonFiles`
+---
 
-Optional array of JSON files for the `sort` command.
+## Example Config
 
 ```js
-sortJsonFiles: [
-  "./src/i18n/locales/translations.en.json",
-  "./src/i18n/locales/translations.es.json",
-];
-```
+export default {
+  srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"],
 
-### `outputDir`
+  jsonDir: [
+    "./src/i18n/locales/translations.en.json",
+    "./src/i18n/locales/translations.es.json",
+  ],
 
-Directory where unused translation reports will be written.
+  sortJsonFiles: [
+    "./src/i18n/locales/translations.en.json",
+    "./src/i18n/locales/translations.es.json",
+  ],
 
-Default:
+  outputDir: "./reports",
 
-```js
-"./unused-translations";
+  syncMissing: false,
+  removeUnused: false,
+  sortJson: true,
+};
 ```
 
-### `syncMissing`
-
-If `true`, missing keys found in code will be added to translation JSON files.
-
-### `removeUnused`
-
-If `true`, unused keys will be removed from translation JSON files.
-
 ---
 
 ## Commands
 
-### Initialize config
+### `init`
+
+Creates config file automatically.
 
 ```bash
 npx react-i18next-scanner init
 ```
 
-This command creates a config file automatically and lets you choose:
-
-- `.js`
-- `.mjs`
-- `.cjs`
-
 ---
 
-### Scan project
+### `scan`
+
+Scans your project and creates reports.
 
 ```bash
 npx react-i18next-scanner scan
 ```
 
-or with custom config:
+With custom config:
 
 ```bash
 npx react-i18next-scanner scan --config ./i18n-scanner.config.mjs
 ```
 
-What it does:
+The `scan` command:
 
 - scans source files
-- extracts translation keys
-- compares them with translation JSON files
-- writes unused translation reports
-- writes dynamic translation usage reports
+- extracts used translation keys
+- compares used keys with translation JSON files
+- detects missing keys
+- detects unused keys
+- detects dynamic translation usages
+- writes reports
 - optionally syncs missing keys
-- optionally removes unused keys
+- optionally removes definitely unused keys
 
 ---
 
-### Sync missing translations
+### `sync-missing`
+
+Finds missing keys and adds them to translation JSON files.
 
 ```bash
 npx react-i18next-scanner sync-missing
 ```
 
-This command:
+Missing keys are added with empty values.
+
+Example:
 
-- scans your source files
-- finds missing translation keys
-- adds them to your translation JSON files
+```json
+{
+  "common": {
+    "Save": ""
+  }
+}
+```
 
 ---
 
-### Sort translation JSON files
+### `sort`
+
+Sorts translation JSON files alphabetically.
 
 ```bash
 npx react-i18next-scanner sort
 ```
 
-If no files are passed manually, the command uses `sortJsonFiles` from config.
+If no files are passed, the command uses `sortJsonFiles` from config.
 
 You can also pass files manually:
 
@@ -182,62 +173,387 @@ npx react-i18next-scanner sort ./src/i18n/locales/translations.en.json ./src/i18
 
 ---
 
+## Report Structure
+
+All reports are written inside one root folder:
+
+```txt
+reports/
+```
+
+Each report type has its own folder:
+
+```txt
+reports/
+  unused-translations/
+    unused.translations.en.json
+    unused.translations.es.json
+
+  dynamic-translations/
+    dynamic-translation-usages.json
+
+  possibly-dynamically-used/
+    possibly-dynamically-used.json
+
+  imported-object-usages/
+    resolved-imported-object-usages.json
+```
+
+---
+
 ## Unused Translation Reports
 
-When unused keys are found, the scanner creates report files inside `outputDir`.
+Folder:
+
+```txt
+reports/unused-translations/
+```
+
+These reports contain translation keys that look unused after deep verification.
 
 Example:
 
-- `translations.en.json` → `unused.translations.en.json`
-- `translations.es.json` → `unused.translations.es.json`
+```txt
+reports/unused-translations/unused.translations.en.json
+```
 
-These files contain only unused translations, so you can review them safely before deleting anything.
+Example content:
+
+```json
+{
+  "common": {
+    "Old button text": "Old button text"
+  }
+}
+```
+
+You can review this file before removing keys.
+
+If `removeUnused: true`, only definitely unused keys will be removed.
 
 ---
 
 ## Dynamic Translation Report
 
-If the scanner finds dynamic translation usage such as:
+Folder:
 
-```ts
-t(getDescription());
-t(labelKey);
-t(transaction.descriptionKey);
+```txt
+reports/dynamic-translations/
 ```
 
-it creates a report file:
+This report shows places where the scanner found dynamic translation usage.
 
-```bash
-reports-dynamic/dynamic-translation-usages.json
+Examples:
+
+```ts
+t(labelKey);
+t(getDescription());
+t(`${section}.${name}`);
+<Trans i18nKey={text} />;
+<Trans i18nKey={`account.${text}`} />;
 ```
 
-Example structure:
+Example report:
 
 ```json
 {
-  "src/views/Account/BalancesTransactionsPage/PaymentDescription.tsx": [
+  "src/components/Profile.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."
+      "namespaces": ["common"],
+      "expression": "labelKey",
+      "reason": "Non-literal translation key",
+      "suggestion": "Translation key may come from a variable or helper function. Manual or deeper analysis may be required."
     }
   ]
 }
 ```
 
+This report answers:
+
+```txt
+Where do we use dynamic translation keys in source code?
+```
+
+---
+
+## Possibly Dynamically Used Report
+
+Folder:
+
+```txt
+reports/possibly-dynamically-used/
+```
+
+This report shows keys that looked unused at first, but were later detected as possibly used dynamically.
+
+Example:
+
+```ts
+const titleKey = MODAL_DATA[type].TITLE;
+
+t(String(titleKey));
+```
+
+The key may not appear directly as:
+
+```ts
+t("accountInformation.Account Number");
+```
+
+But the scanner can understand that it may come from an object config.
+
+This report answers:
+
+```txt
+Which unused keys were saved from removal because they may be used dynamically?
+```
+
+---
+
+## Imported Object Usages Report
+
+Folder:
+
+```txt
+reports/imported-object-usages/
+```
+
+File:
+
+```txt
+resolved-imported-object-usages.json
+```
+
+This report shows where translation keys from imported object configs are used.
+
+Example config object:
+
+```ts
+export const MODAL_DATA = {
+  accountNumber: {
+    TITLE: "accountInformation.Account Number",
+    TEXT: "accountInformation.Your Account Number is",
+  },
+};
+```
+
+Example usage:
+
+```ts
+import { MODAL_DATA } from "./modalData";
+
+const additionalInformationData = MODAL_DATA[additionalInformationModalType];
+
+t(String(additionalInformationData.TITLE));
+```
+
+The scanner can resolve this as:
+
+```txt
+additionalInformationData.TITLE
+→ MODAL_DATA[*].TITLE
+→ accountInformation.Account Number
+```
+
+Example report:
+
+```json
+[
+  {
+    "key": "accountInformation.Account Number",
+    "sourceFilePath": "src/components/AdditionalInformationModal.tsx",
+    "importedFilePath": "src/config/modalData.ts",
+    "importedObjectName": "MODAL_DATA",
+    "accessPath": "MODAL_DATA.*.TITLE",
+    "usageKind": "t"
+  }
+]
+```
+
+This report answers:
+
+```txt
+Where is this imported object translation key used?
+```
+
 ---
 
 ## Supported Translation Patterns
 
-The scanner currently detects translation keys used with:
+The scanner detects direct translation keys:
+
+```ts
+t("common.Save");
+i18n.t("common.Save");
+<Trans i18nKey="common.Save" />;
+```
+
+It also supports namespaces:
+
+```ts
+const { t } = useTranslation("common");
+
+t("Save");
+```
+
+---
+
+## Supported Dynamic Patterns
+
+The scanner can detect and report dynamic usages:
+
+```ts
+t(labelKey);
+t(getTitleKey());
+t(`${section}.${name}`);
+<Trans i18nKey={labelKey} />;
+<Trans i18nKey={`account.${name}`} />;
+```
+
+It can also resolve some imported object config usages:
+
+```ts
+t(String(MODAL_DATA[type].TITLE));
+```
+
+```ts
+const data = MODAL_DATA[type];
+
+t(String(data.TITLE));
+```
+
+```tsx
+<Trans i18nKey={MODAL_DATA[type].TITLE} />
+```
+
+This works not only for `MODAL_DATA`, but also for similar exported object configs:
+
+```ts
+export const WARNING_CONFIG = {
+  deleteAccount: {
+    TITLE: "settings.Delete account",
+    TEXT: "settings.This action cannot be undone",
+  },
+};
+```
+
+---
+
+## Config Options
+
+### `srcPaths`
+
+Source files to scan.
+
+```js
+srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"];
+```
+
+---
+
+### `jsonDir`
+
+Translation JSON files to analyze.
+
+```js
+jsonDir: [
+  "./src/i18n/locales/translations.en.json",
+  "./src/i18n/locales/translations.es.json",
+];
+```
+
+---
+
+### `sortJsonFiles`
+
+JSON files used by the `sort` command.
+
+```js
+sortJsonFiles: [
+  "./src/i18n/locales/translations.en.json",
+  "./src/i18n/locales/translations.es.json",
+];
+```
+
+---
+
+### `outputDir`
+
+Root folder for scanner reports.
+
+Default:
+
+```js
+outputDir: "./reports";
+```
+
+Reports will be grouped into subfolders:
+
+```txt
+reports/
+  unused-translations/
+  dynamic-translations/
+  possibly-dynamically-used/
+  imported-object-usages/
+```
+
+---
+
+### `syncMissing`
+
+If `true`, missing keys found in code will be added to translation JSON files.
+
+```js
+syncMissing: true;
+```
+
+Values are created as empty strings.
+
+---
+
+### `removeUnused`
+
+If `true`, definitely unused keys will be removed from translation JSON files.
+
+```js
+removeUnused: true;
+```
+
+The scanner does not remove keys that are possibly dynamically used.
+
+---
+
+### `sortJson`
+
+If `true`, JSON files will be sorted after sync or remove actions.
+
+```js
+sortJson: true;
+```
+
+---
+
+## Safe Remove Behavior
 
-- `t("key")`
-- `i18n.t("key")`
-- `<Trans i18nKey="key" />`
-- `useTranslation("namespace")`
+The scanner tries to avoid removing keys that may still be used dynamically.
 
-It can also report dynamic usages where translation keys are not passed directly as string literals.
+For example:
+
+```ts
+const data = MODAL_DATA[type];
+
+t(String(data.TITLE));
+```
+
+If `MODAL_DATA[type].TITLE` contains:
+
+```ts
+"accountInformation.Account Number";
+```
+
+then this key will not be treated as definitely unused.
+
+It will be moved to a dynamic safety report instead.
 
 ---
 
@@ -245,20 +561,20 @@ It can also report dynamic usages where translation keys are not passed directly
 
 ### Source files
 
-The scanner can scan:
-
-- `.js`
-- `.jsx`
-- `.ts`
-- `.tsx`
+```txt
+.js
+.jsx
+.ts
+.tsx
+```
 
 ### Config files
 
-The scanner currently supports:
-
-- `.js`
-- `.cjs`
-- `.mjs`
+```txt
+.js
+.cjs
+.mjs
+```
 
 > `.ts` config is not supported yet.
 
@@ -266,12 +582,15 @@ The scanner currently supports:
 
 ## Example Workflow
 
-### 1. Scan without modifying JSON files
+### 1. Scan only
+
+Use this when you want reports without modifying translation JSON files.
 
 ```js
 export default {
   srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"],
   jsonDir: ["./src/i18n/locales/translations.en.json"],
+  outputDir: "./reports",
   syncMissing: false,
   removeUnused: false,
 };
@@ -283,12 +602,15 @@ Run:
 npx react-i18next-scanner scan
 ```
 
+---
+
 ### 2. Sync missing keys
 
 ```js
 export default {
   srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"],
   jsonDir: ["./src/i18n/locales/translations.en.json"],
+  outputDir: "./reports",
   syncMissing: true,
   removeUnused: false,
 };
@@ -300,18 +622,21 @@ Run:
 npx react-i18next-scanner scan
 ```
 
-or
+or:
 
 ```bash
 npx react-i18next-scanner sync-missing
 ```
 
-### 3. Remove unused keys
+---
+
+### 3. Remove definitely unused keys
 
 ```js
 export default {
   srcPaths: ["./src/**/*.{js,jsx,ts,tsx}"],
   jsonDir: ["./src/i18n/locales/translations.en.json"],
+  outputDir: "./reports",
   syncMissing: false,
   removeUnused: true,
 };
@@ -323,14 +648,46 @@ Run:
 npx react-i18next-scanner scan
 ```
 
+Before using `removeUnused: true`, review reports first.
+
+---
+
+## Limitations
+
+The scanner does not fully support every possible runtime data-flow case.
+
+Currently not fully covered:
+
+```ts
+const data = getModalData(type);
+t(data.TITLE);
+```
+
+```ts
+const key = MODAL_DATA[type].TITLE + ".extra";
+t(key);
+```
+
+```ts
+const data = someWrapper(MODAL_DATA[type]);
+t(data.TITLE);
+```
+
+```ts
+export default MODAL_DATA;
+```
+
+The scanner is designed to be safe. If it is not sure, it reports dynamic usage instead of removing keys automatically.
+
 ---
 
 ## Notes
 
-- `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.
+- `syncMissing` does not translate values automatically.
+- `removeUnused` should be used carefully.
+- Possibly dynamic keys are not removed automatically.
 - Config paths are resolved relative to the config file location.
+- `.ts` config is not supported yet.
 
 ---
 
@@ -342,7 +699,7 @@ Build the project:
 yarn build
 ```
 
-Run CLI in development mode:
+Run scanner in development:
 
 ```bash
 yarn dev scan

package/dist/core/actions/writeDynamicTranslationReport.js

@@ -1,7 +1,7 @@
 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");
+const DEFAULT_DYNAMIC_REPORT_DIR = path.resolve(process.cwd(), "reports/dynamic-translations");
 export async function writeDynamicTranslationReport(report, outputDir = DEFAULT_DYNAMIC_REPORT_DIR) {
     if (Object.keys(report).length === 0) {
         return;

package/dist/core/actions/writePossiblyDynamicallyUsedReport.js

@@ -3,7 +3,7 @@ import fs from "fs/promises";
 import path from "path";
 import { addKey } from "../utils/addKey.js";
 import { sortObject } from "../utils/sortObject.js";
-const DEFAULT_OUTPUT_DIR = path.resolve(process.cwd(), "reports-dynamic");
+const DEFAULT_OUTPUT_DIR = path.resolve(process.cwd(), "dynamic-translations");
 export async function writePossiblyDynamicallyUsedReport(keysByFile, jsonFiles, outputDir = DEFAULT_OUTPUT_DIR) {
     const reportDataByFile = {};
     for (const file of jsonFiles) {

package/dist/core/actions/writeResolvedImportedObjectUsageReport.js

@@ -5,7 +5,8 @@ export async function writeResolvedImportedObjectUsagesReport(usages, outputDir)
     if (usages.length === 0) {
         return;
     }
-    const reportDir = outputDir ?? "reports";
+    const rootReportDir = outputDir ?? "reports";
+    const reportDir = path.join(rootReportDir, "imported-object-usages");
     await fs.mkdir(reportDir, { recursive: true });
     const reportPath = path.join(reportDir, "resolved-imported-object-usages.json");
     await fs.writeFile(reportPath, JSON.stringify(usages, null, 2), "utf-8");

package/dist/core/actions/writeUnusedTranslationsReport.js

@@ -10,7 +10,9 @@ export async function writeUnusedTranslationsReport(keysByFile, jsonFiles, outpu
     if (filesWithUnused.length === 0) {
         return;
     }
-    await fs.mkdir(outputDir, { recursive: true });
+    const rootReportDir = outputDir ?? "reports";
+    const reportDir = path.join(rootReportDir, "unused-translations");
+    await fs.mkdir(reportDir, { recursive: true });
     for (const file of filesWithUnused) {
         const unusedKeys = keysByFile[file.filePath] ?? [];
         const reportData = {};
@@ -22,7 +24,7 @@ export async function writeUnusedTranslationsReport(keysByFile, jsonFiles, outpu
         }
         const sorted = sortObject(reportData);
         const reportFileName = `unused.${path.basename(file.filePath)}`;
-        const reportPath = path.join(outputDir, reportFileName);
+        const reportPath = path.join(reportDir, reportFileName);
         await fs.writeFile(reportPath, JSON.stringify(sorted, null, 2), "utf-8");
         console.log(`📝 Unused report created: ${reportPath}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-i18next-scanner",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CLI tool to scan React projects for missing and unused react-i18next translation keys",
   "bin": "./dist/cli/cli.js",
   "scripts": {