@messagevisor/module-missing-translations 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.1.0](https://github.com/messagevisor/messagevisor/compare/v0.0.2...v0.1.0) (2026-05-31)
+
+**Note:** Version bump only for package @messagevisor/module-missing-translations
+
+
+
+
+
+## 0.0.2 (2026-05-31)
+
+**Note:** Version bump only for package @messagevisor/module-missing-translations

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Fahad Heylaal (https://fahad19.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @messagevisor/module-missing-translations
+
+Visit [https://messagevisor.com/docs/modules/missing-translations/](https://messagevisor.com/docs/modules/missing-translations/) for more information.
+
+## License
+
+MIT © [Fahad Heylaal](https://fahad19.com)

package/jest.config.js

@@ -0,0 +1,11 @@
+const base = require("../../jest.config");
+
+module.exports = {
+  ...base,
+  rootDir: "../..",
+  testRegex: undefined,
+  testMatch: ["<rootDir>/packages/module-missing-translations/src/**/*.spec.ts"],
+  moduleNameMapper: {
+    "^@messagevisor/sdk$": "<rootDir>/packages/sdk/src/index.ts",
+  },
+};

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+import type { MessagevisorDiagnostic, MessagevisorModule, MessagevisorTranslationSource } from "@messagevisor/sdk";
+export interface MissingTranslationPayload {
+    messageKey: string;
+    locale: string | null;
+    revision?: string;
+    source?: MessagevisorTranslationSource;
+    diagnostic: MessagevisorDiagnostic;
+}
+export interface MissingTranslationsModuleOptions {
+    name?: string;
+    handler: (payload: MissingTranslationPayload) => void;
+    dedupe?: boolean;
+}
+export declare function createMissingTranslationsModule(options: MissingTranslationsModuleOptions): MessagevisorModule;

package/lib/index.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMissingTranslationsModule = createMissingTranslationsModule;
+function getDedupeKey(payload) {
+    return JSON.stringify([
+        payload.messageKey,
+        payload.locale,
+        payload.revision || null,
+        payload.source || null,
+    ]);
+}
+function createMissingTranslationsModule(options) {
+    const name = (options === null || options === void 0 ? void 0 : options.name) || "missing-translations";
+    const handler = options === null || options === void 0 ? void 0 : options.handler;
+    const dedupe = (options === null || options === void 0 ? void 0 : options.dedupe) === true;
+    const seen = new Set();
+    return {
+        name,
+        setup({ getRevision, onDiagnostic }) {
+            if (typeof handler !== "function") {
+                throw new Error("Missing translations module requires a handler.");
+            }
+            onDiagnostic((diagnostic) => {
+                if (diagnostic.code !== "missing_translation" || !diagnostic.messageKey) {
+                    return;
+                }
+                const locale = diagnostic.locale || null;
+                let revision;
+                if (locale) {
+                    try {
+                        revision = getRevision(locale);
+                    }
+                    catch (_a) {
+                        revision = undefined;
+                    }
+                }
+                const payload = {
+                    messageKey: diagnostic.messageKey,
+                    locale,
+                    revision,
+                    source: diagnostic.source,
+                    diagnostic,
+                };
+                if (dedupe) {
+                    const dedupeKey = getDedupeKey(payload);
+                    if (seen.has(dedupeKey)) {
+                        return;
+                    }
+                    seen.add(dedupeKey);
+                }
+                handler(payload);
+            }, { logLevel: "error" });
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AA6BA,0EAwDC;AAjED,SAAS,YAAY,CAAC,OAAkC;IACtD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,MAAM;QACd,OAAO,CAAC,QAAQ,IAAI,IAAI;QACxB,OAAO,CAAC,MAAM,IAAI,IAAI;KACvB,CAAC,CAAC;AACL,CAAC;AAED,SAAgB,+BAA+B,CAC7C,OAAyC;IAEzC,MAAM,IAAI,GAAG,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,KAAI,sBAAsB,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC;IACjC,MAAM,MAAM,GAAG,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,MAAK,IAAI,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE;YACjC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;YACrE,CAAC;YAED,YAAY,CACV,CAAC,UAAU,EAAE,EAAE;gBACb,IAAI,UAAU,CAAC,IAAI,KAAK,qBAAqB,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;oBACxE,OAAO;gBACT,CAAC;gBAED,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC;gBACzC,IAAI,QAA4B,CAAC;gBAEjC,IAAI,MAAM,EAAE,CAAC;oBACX,IAAI,CAAC;wBACH,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;oBACjC,CAAC;oBAAC,WAAM,CAAC;wBACP,QAAQ,GAAG,SAAS,CAAC;oBACvB,CAAC;gBACH,CAAC;gBAED,MAAM,OAAO,GAA8B;oBACzC,UAAU,EAAE,UAAU,CAAC,UAAU;oBACjC,MAAM;oBACN,QAAQ;oBACR,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,UAAU;iBACX,CAAC;gBAEF,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;oBAExC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;wBACxB,OAAO;oBACT,CAAC;oBAED,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACtB,CAAC;gBAED,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,EACD,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,15 +1,44 @@
 {
-	"name": "@messagevisor/module-missing-translations",
-	"version": "0.0.1",
-	"description": "Messagevisor package",
-	"license": "ISC",
-	"author": "",
-	"type": "commonjs",
-	"main": "index.js",
-	"publishConfig": {
-		"access": "public"
-	},
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	}
+  "name": "@messagevisor/module-missing-translations",
+  "version": "0.1.0",
+  "description": "Missing translations reporting module for Messagevisor",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "require": "./lib/index.js",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "transpile": "rimraf lib && tsc --project tsconfig.cjs.json",
+    "dist": "echo 'Nothing to dist here'",
+    "build": "npm run transpile",
+    "test": "jest --config jest.config.js --verbose",
+    "typecheck": "tsc --noEmit --skipLibCheck -p tsconfig.typecheck.json"
+  },
+  "author": {
+    "name": "Fahad Heylaal",
+    "url": "https://fahad19.com"
+  },
+  "homepage": "https://messagevisor.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/messagevisor/messagevisor.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bugs": {
+    "url": "https://github.com/messagevisor/messagevisor/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@messagevisor/sdk": "0.1.0"
+  },
+  "gitHead": "555119ab05473127a658ed0cfb6a2743ea3a6db8"
 }

package/src/index.spec.ts

@@ -0,0 +1,130 @@
+import { createMessagevisor } from "@messagevisor/sdk";
+import type { DatafileContent } from "@messagevisor/types";
+
+import { createMissingTranslationsModule, type MissingTranslationPayload } from "./index";
+
+const datafile: DatafileContent = {
+  schemaVersion: "1",
+  messagevisorVersion: "0.0.1",
+  revision: "rev-1",
+  target: "web",
+  locale: "en-US",
+  segments: {},
+  messages: {
+    greeting: {},
+  },
+  translations: {
+    greeting: "Hello",
+  },
+};
+
+describe("@messagevisor/module-missing-translations", function () {
+  it("calls the handler when a translation is missing", function () {
+    const calls: MissingTranslationPayload[] = [];
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "fatal",
+      modules: [
+        createMissingTranslationsModule({
+          handler(payload) {
+            calls.push(payload);
+          },
+        }),
+      ],
+    });
+
+    expect(m.translate("missing.key")).toEqual("missing.key");
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      messageKey: "missing.key",
+      locale: "en-US",
+      revision: "rev-1",
+      source: "translation",
+      diagnostic: {
+        code: "missing_translation",
+        level: "error",
+        messageKey: "missing.key",
+        locale: "en-US",
+      },
+    });
+  });
+
+  it("does not call the handler for non-missing diagnostics or successful translations", function () {
+    const calls: MissingTranslationPayload[] = [];
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "fatal",
+      modules: [
+        createMissingTranslationsModule({
+          handler(payload) {
+            calls.push(payload);
+          },
+        }),
+      ],
+    });
+
+    expect(m.translate("greeting")).toEqual("Hello");
+    expect(calls).toEqual([]);
+  });
+
+  it("calls the handler every time by default", function () {
+    const calls: MissingTranslationPayload[] = [];
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "fatal",
+      modules: [
+        createMissingTranslationsModule({
+          handler(payload) {
+            calls.push(payload);
+          },
+        }),
+      ],
+    });
+
+    m.translate("missing.key");
+    m.translate("missing.key");
+
+    expect(calls.map((call) => call.messageKey)).toEqual(["missing.key", "missing.key"]);
+  });
+
+  it("dedupes repeated missing translations when enabled", function () {
+    const calls: MissingTranslationPayload[] = [];
+    const m = createMessagevisor({
+      datafile,
+      logLevel: "fatal",
+      modules: [
+        createMissingTranslationsModule({
+          dedupe: true,
+          handler(payload) {
+            calls.push(payload);
+          },
+        }),
+      ],
+    });
+
+    m.translate("missing.key");
+    m.translate("missing.key");
+    m.getRawTranslation("missing.key");
+    m.translate("another.missing");
+
+    expect(calls.map((call) => call.messageKey)).toEqual(["missing.key", "another.missing"]);
+  });
+
+  it("requires a handler", function () {
+    expect(() =>
+      createMessagevisor({
+        datafile,
+        logLevel: "fatal",
+        modules: [createMissingTranslationsModule({} as any)],
+      }),
+    ).toThrow("Missing translations module requires a handler.");
+  });
+
+  it("uses a stable default module name and supports custom names", function () {
+    expect(createMissingTranslationsModule({ handler() {} }).name).toEqual("missing-translations");
+    expect(createMissingTranslationsModule({ name: "tracker", handler() {} }).name).toEqual(
+      "tracker",
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,86 @@
+import type {
+  MessagevisorDiagnostic,
+  MessagevisorModule,
+  MessagevisorTranslationSource,
+} from "@messagevisor/sdk";
+
+export interface MissingTranslationPayload {
+  messageKey: string;
+  locale: string | null;
+  revision?: string;
+  source?: MessagevisorTranslationSource;
+  diagnostic: MessagevisorDiagnostic;
+}
+
+export interface MissingTranslationsModuleOptions {
+  name?: string;
+  handler: (payload: MissingTranslationPayload) => void;
+  dedupe?: boolean;
+}
+
+function getDedupeKey(payload: MissingTranslationPayload) {
+  return JSON.stringify([
+    payload.messageKey,
+    payload.locale,
+    payload.revision || null,
+    payload.source || null,
+  ]);
+}
+
+export function createMissingTranslationsModule(
+  options: MissingTranslationsModuleOptions,
+): MessagevisorModule {
+  const name = options?.name || "missing-translations";
+  const handler = options?.handler;
+  const dedupe = options?.dedupe === true;
+  const seen = new Set<string>();
+
+  return {
+    name,
+    setup({ getRevision, onDiagnostic }) {
+      if (typeof handler !== "function") {
+        throw new Error("Missing translations module requires a handler.");
+      }
+
+      onDiagnostic(
+        (diagnostic) => {
+          if (diagnostic.code !== "missing_translation" || !diagnostic.messageKey) {
+            return;
+          }
+
+          const locale = diagnostic.locale || null;
+          let revision: string | undefined;
+
+          if (locale) {
+            try {
+              revision = getRevision(locale);
+            } catch {
+              revision = undefined;
+            }
+          }
+
+          const payload: MissingTranslationPayload = {
+            messageKey: diagnostic.messageKey,
+            locale,
+            revision,
+            source: diagnostic.source,
+            diagnostic,
+          };
+
+          if (dedupe) {
+            const dedupeKey = getDedupeKey(payload);
+
+            if (seen.has(dedupeKey)) {
+              return;
+            }
+
+            seen.add(dedupeKey);
+          }
+
+          handler(payload);
+        },
+        { logLevel: "error" },
+      );
+    },
+  };
+}

package/tsconfig.cjs.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.cjs.json",
+  "compilerOptions": {
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "target": "es2018",
+    "lib": ["es2021", "es2021.intl", "dom"],
+    "skipLibCheck": true
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.spec.ts"]
+}

package/tsconfig.typecheck.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.cjs.json",
+  "exclude": []
+}