@lingual/i18n-check 0.1.5 → 0.2.0

package/README.md

@@ -1,4 +1,13 @@
-# Lingual i18n Check
+# Lingual i18n-check
+
+**i18n-check** will help with validating your translation files, including
+checking for missing and/or invalid/broken translations.
+It will compare the defined source language with all target translation files and try to find inconsistencies between source and target files.
+You can run these checks as a pre-commit hook or on the CI depending on your use-case and setup.
+
+![example 1](./assets/i18n-check-example-one.png)
+
+![example 2](./assets/i18n-check-example-two.png)
 
 ## Installation and Usage
 
@@ -66,6 +75,8 @@ Additionally the `i18next` format is supported and can be set via the `-f` or `-
 
 There are i18n libraries that have their own specific format, which might not be based on `icu` and therefore can not be validated against currently. On a side-note: there might be future support for more specific formats.
 
+Hint: If you want to use the `--unused` flag, you should provide `react-intl` as the format. Also see the [`unused` section](#--unused) for more details.
+
 ```bash
 yarn i18n:check -t translations/i18NextMessageExamples -s translations/i18NextMessageExamples/en-us.json -f i18next
 ```
@@ -94,6 +105,16 @@ Check for missing an invalid keys (which is the default):
 yarn i18n:check -t translations/messageExamples -s translations/messageExamples/en-us.json -c missingKeys,invalidKeys
 ```
 
+### --unused
+
+This feature is currently only supported for `react-intl` and is useful if you need to know which keys exist in your translation files but not in your codebase. Via the `-u` or `--unused` option you provide a source path to the code, which will be parsed to find all unused keys in the primay target language.
+
+It is important to note that you must also provide the `-f` or `--format` option with `react-intl` as value. See the [`format` section](#--format) for more information.
+
+```bash
+yarn i18n:check -t translations/messageExamples -s translations/messageExamples/en-us.json -u client/ -f react-intl
+```
+
 ### --reporter
 
 The standard reporting prints out all the missing or invalid keys.
@@ -146,7 +167,7 @@ If all the locales are organized in a **single folder**:
   - en-en.json
   - de-de.json
 
-Use the `d` or `dir` option to define the directory that should be checked for target files. With the `s` or `source` option you can specify the base/reference file to compare the target files against.
+Use the `t` or `target` option to define the directory that should be checked for target files. With the `s` or `source` option you can specify the base/reference file to compare the target files against.
 
 ```bash
 yarn i18n:check -t locales -s locales/en-us.json
@@ -216,7 +237,7 @@ If the locales are **organised as folders** containing multiple json files:
 Define the `locales` folder as the directory to look for target files and pass `locales/en-US/` as the `source` option. `i18n-check` will try to collect all the files in the provided source directory and compare each one against the corresponding files in the target locales.
 
 ```bash
-yarn i18n:check -t dirOne,dirTwo -s dirOne/en/,dirTwo/de
+yarn i18n:check -t dirOne,dirTwo -s dirOne/en/,dirTwo/en
 ```
 
 ## As Github Action
@@ -400,3 +421,7 @@ To run the tests use the following command:
 ```bash
 pnpm run test // yarn test or npm test
 ```
+
+## Links
+
+[Twitter](https://twitter.com/lingualdev)

package/dist/bin/index.js

@@ -29,6 +29,7 @@ commander_1.program
     .option("-c, --check [checks]", "define the specific checks you want to run: invalid, missing. By default the check will validate against missing and invalid keys, i.e. --check invalidKeys,missingKeys")
     .option("-r, --reporter [error reporting style]", "define the reporting style: standard or summary")
     .option("-e, --exclude [file(s), folder(s)]", "define the file(s) and/or folders(s) that should be excluded from the check")
+    .option("-u, --unused [folder]", "define the source path to find all unused keys")
     .parse();
 const getCheckOptions = () => {
     const checkOption = commander_1.program.getOptionValue("check");
@@ -66,6 +67,7 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
     const targetPath = commander_1.program.getOptionValue("target");
     const format = commander_1.program.getOptionValue("format");
     const exclude = commander_1.program.getOptionValue("exclude");
+    const unusedSrcPath = commander_1.program.getOptionValue("unused");
     if (!srcPath) {
         console.log(chalk_1.default.red("Source file(s) not found. Please provide valid source file(s), i.e. -s translations/en-us.json"));
         (0, process_1.exit)(1);
@@ -86,8 +88,8 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
     const files = yield (0, glob_1.glob)(pattern, {
         ignore: ["node_modules/**"].concat(excludedPaths),
     });
-    console.log(chalk_1.default.blue("i18n translations checker"));
-    console.log(chalk_1.default.blackBright(`Source file(s): ${srcPath}`));
+    console.log("i18n translations checker");
+    console.log(chalk_1.default.gray(`Source file(s): ${srcPath}`));
     if (format) {
         console.log(chalk_1.default.blackBright(`Selected format is: ${format}`));
     }
@@ -127,7 +129,11 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
     }
     try {
         const result = (0, __1.checkTranslations)(srcFiles, targetFiles, options);
-        print(result);
+        printTranslationResult(result);
+        if (unusedSrcPath) {
+            const unusedKeys = yield (0, __1.checkUnusedKeys)(srcFiles, unusedSrcPath, options);
+            printUnusedKeysResult({ unusedKeys });
+        }
         const end = performance.now();
         console.log(chalk_1.default.green(`\nDone in ${Math.round(((end - start) * 100) / 1000) / 100}s.`));
         if ((result.missingKeys && Object.keys(result.missingKeys).length > 0) ||
@@ -143,28 +149,71 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
         (0, process_1.exit)(1);
     }
 });
-const print = ({ missingKeys, invalidKeys, }) => {
+const printTranslationResult = ({ missingKeys, invalidKeys, }) => {
     const reporter = commander_1.program.getOptionValue("reporter");
-    const errorReporter = reporter === "summary" ? errorReporters_1.summaryReporter : errorReporters_1.standardReporter;
+    const isSummary = reporter === "summary";
     if (missingKeys && Object.keys(missingKeys).length > 0) {
-        console.log(chalk_1.default.bgRed(chalk_1.default.white("\nFound missing keys!")));
-        for (const [lang, missingMessageKeys] of Object.entries(missingKeys)) {
-            console.log(chalk_1.default.red(`\nIn ${lang}:\n`));
-            console.log(chalk_1.default.red(errorReporter(missingMessageKeys, "missingKeys")));
+        console.log(chalk_1.default.red("\nFound missing keys!"));
+        if (isSummary) {
+            console.log(chalk_1.default.red((0, errorReporters_1.summaryReporter)(getSummaryRows(missingKeys))));
+        }
+        else {
+            console.log(chalk_1.default.red((0, errorReporters_1.standardReporter)(getStandardRows(missingKeys))));
         }
     }
     else if (missingKeys) {
         console.log(chalk_1.default.green("\nNo missing keys found!"));
     }
     if (invalidKeys && Object.keys(invalidKeys).length > 0) {
-        console.log(chalk_1.default.bgRed(chalk_1.default.white("\nFound invalid keys!")));
-        for (const [lang, invalidMessageKeys] of Object.entries(invalidKeys)) {
-            console.log(chalk_1.default.red(`\nIn ${lang}:\n`));
-            console.log(chalk_1.default.red(errorReporter(invalidMessageKeys, "invalidKeys")));
+        console.log(chalk_1.default.red("\nFound invalid keys!"));
+        if (isSummary) {
+            console.log(chalk_1.default.red((0, errorReporters_1.summaryReporter)(getSummaryRows(invalidKeys))));
+        }
+        else {
+            console.log(chalk_1.default.red((0, errorReporters_1.standardReporter)(getStandardRows(invalidKeys))));
         }
     }
     else if (invalidKeys) {
         console.log(chalk_1.default.green("\nNo invalid translations found!"));
     }
 };
+const printUnusedKeysResult = ({ unusedKeys, }) => {
+    const reporter = commander_1.program.getOptionValue("reporter");
+    const isSummary = reporter === "summary";
+    if (unusedKeys && Object.keys(unusedKeys).length > 0) {
+        console.log(chalk_1.default.red("\nFound unused keys!"));
+        if (isSummary) {
+            console.log(chalk_1.default.red((0, errorReporters_1.summaryReporter)(getSummaryRows(unusedKeys))));
+        }
+        else {
+            console.log(chalk_1.default.red((0, errorReporters_1.standardReporter)(getStandardRows(unusedKeys))));
+        }
+    }
+    else if (unusedKeys) {
+        console.log(chalk_1.default.green("\nNo unused found!"));
+    }
+};
+const truncate = (chars) => chars.length > 80 ? `${chars.substring(0, 80)}...` : chars;
+const getSummaryRows = (checkResult) => {
+    const formattedRows = [];
+    for (const [file, keys] of Object.entries(checkResult)) {
+        formattedRows.push({
+            file: truncate(file),
+            total: keys.length,
+        });
+    }
+    return formattedRows;
+};
+const getStandardRows = (checkResult) => {
+    const formattedRows = [];
+    for (const [file, keys] of Object.entries(checkResult)) {
+        for (const key of keys) {
+            formattedRows.push({
+                file: truncate(file),
+                key: truncate(key),
+            });
+        }
+    }
+    return formattedRows;
+};
 main();

package/dist/errorReporters.d.ts

@@ -1,5 +1,11 @@
 export type Context = "missingKeys" | "invalidKeys";
-export type ErrorReporter = (result: string[], context: Context) => void;
 export declare const contextMapping: Record<Context, string>;
-export declare const standardReporter: ErrorReporter;
-export declare const summaryReporter: ErrorReporter;
+export declare const standardReporter: (result: {
+    file: string;
+    key: string;
+}[]) => string;
+export declare const summaryReporter: (result: {
+    file: string;
+    total: number;
+}[]) => string;
+export declare const createTable: (input: unknown[]) => string;

package/dist/errorReporters.js

@@ -1,16 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.summaryReporter = exports.standardReporter = exports.contextMapping = void 0;
+exports.createTable = exports.summaryReporter = exports.standardReporter = exports.contextMapping = void 0;
+const console_1 = require("console");
+const stream_1 = require("stream");
 exports.contextMapping = {
     invalidKeys: "invalid",
     missingKeys: "missing",
 };
 const standardReporter = (result) => {
-    return result.map((key) => `◯ ${key}`).join("\n");
+    return (0, exports.createTable)(result.map(({ file, key }) => ({ file, key })));
 };
 exports.standardReporter = standardReporter;
-const summaryReporter = (result, context) => {
-    const count = result.length;
-    return `Found ${count} ${exports.contextMapping[context]} ${count === 1 ? "key" : "keys"}.`;
+const summaryReporter = (result) => {
+    return (0, exports.createTable)(result.map(({ file, total }) => ({ file, total })));
 };
 exports.summaryReporter = summaryReporter;
+const createTable = (input) => {
+    // https://stackoverflow.com/a/67859384
+    const ts = new stream_1.Transform({
+        transform(chunk, enc, cb) {
+            cb(null, chunk);
+        },
+    });
+    const logger = new console_1.Console({ stdout: ts });
+    logger.table(input);
+    const table = (ts.read() || "").toString();
+    // https://stackoverflow.com/a/69874540
+    let output = "";
+    for (let line of table.split(/[\r\n]+/)) {
+        output += `${line
+            .replace(/[^┬]*┬/, "┌")
+            .replace(/^├─*┼/, "├")
+            .replace(/│[^│]*/, "")
+            .replace(/^└─*┴/, "└")
+            .replace(/'/g, " ")}\n`;
+    }
+    return output;
+};
+exports.createTable = createTable;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { CheckResult, Translation, TranslationFile } from "./types";
 import { Context } from "./errorReporters";
 export type Options = {
-    format?: "icu" | "i18next";
+    format?: "icu" | "i18next" | "react-intl" | "react-i18next";
     checks?: Context[];
 };
 export declare const checkInvalidTranslations: (source: Translation, targets: Record<string, Translation>, options?: Options) => CheckResult;
@@ -10,3 +10,4 @@ export declare const checkTranslations: (source: TranslationFile[], targets: Tra
     missingKeys: CheckResult | undefined;
     invalidKeys: CheckResult | undefined;
 };
+export declare const checkUnusedKeys: (source: TranslationFile[], codebaseSrc: string, options?: Options) => Promise<CheckResult | undefined>;

package/dist/index.js

@@ -1,9 +1,20 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkTranslations = exports.checkMissingTranslations = exports.checkInvalidTranslations = void 0;
+exports.checkUnusedKeys = exports.checkTranslations = exports.checkMissingTranslations = exports.checkInvalidTranslations = void 0;
 const findMissingKeys_1 = require("./utils/findMissingKeys");
 const findInvalidTranslations_1 = require("./utils/findInvalidTranslations");
 const findInvalidi18nTranslations_1 = require("./utils/findInvalidi18nTranslations");
+const glob_1 = require("glob");
+const cli_lib_1 = require("@formatjs/cli-lib");
 const checkInvalidTranslations = (source, targets, options = { format: "icu" }) => {
     return options.format === "i18next"
         ? (0, findInvalidi18nTranslations_1.findInvalid18nTranslations)(source, targets)
@@ -39,3 +50,34 @@ const checkTranslations = (source, targets, options = { format: "icu", checks: [
     };
 };
 exports.checkTranslations = checkTranslations;
+const checkUnusedKeys = (source, codebaseSrc, options = {
+    format: "react-intl",
+}) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!options.format || !["react-intl", "i18next"].includes(options.format)) {
+        return undefined;
+    }
+    return options.format === "react-intl"
+        ? findUnusedReactIntlTranslations(source, codebaseSrc)
+        : undefined;
+});
+exports.checkUnusedKeys = checkUnusedKeys;
+const findUnusedReactIntlTranslations = (source, codebaseSrc) => __awaiter(void 0, void 0, void 0, function* () {
+    let unusedKeys = {};
+    // find any unused keys in a react-intl code base
+    const unsuedKeysFiles = (0, glob_1.globSync)(codebaseSrc, {
+        ignore: ["node_modules/**"],
+    });
+    const extracted = yield (0, cli_lib_1.extract)(unsuedKeysFiles, {});
+    const extractedResultSet = new Set(Object.keys(JSON.parse(extracted)));
+    source.forEach(({ name, content }) => {
+        const keysInSource = Object.keys(content);
+        const found = [];
+        for (const keyInSource of keysInSource) {
+            if (!extractedResultSet.has(keyInSource)) {
+                found.push(keyInSource);
+            }
+        }
+        Object.assign(unusedKeys, { [name]: found });
+    });
+    return unusedKeys;
+});

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@lingual/i18n-check",
-  "version": "0.1.5",
+  "version": "0.2.0",
+  "description": "i18n translation messages check",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -16,6 +17,7 @@
     "dist/"
   ],
   "dependencies": {
+    "@formatjs/cli-lib": "^6.4.2",
     "@formatjs/icu-messageformat-parser": "^2.7.6",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
@@ -25,7 +27,12 @@
   "devDependencies": {
     "@types/jest": "^29.5.12",
     "@types/node": "^20.12.12",
+    "braces": ">=3.0.3",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lingualdev/i18n-check.git"
   }
 }