@npm-questionpro/wick-ui-i18n 0.8.0 → 0.10.0

package/index.js

@@ -1,181 +1,95 @@
-import { createFilter } from "vite";
-import MagicString from "magic-string";
-import { parse } from "@babel/parser";
-import _traverse from "@babel/traverse";
-
-const traverse = _traverse.default || _traverse;
-
-class TranslationProcessor {
-  constructor(options) {
-    this.components = new Set(options.components);
-    this.ignoreComponents = new Set(
-      [
-        "WuIcon",
-        "WuTranslateProvider",
-        "WuHelpButton",
-        "WuActivityLog",
-        "WuAppHeader",
-        "WuAPpHeadeMenu",
-        "WuCopyToClipboard",
-        "WuMenuIcon",
-        "WuScrollArea",
-        "WuDrawer",
-        "WuLoader",
-        "WuContentEditor",
-      ].concat(options.ignoreComponents || []),
-    );
-    this.dictionary = new Map();
-    this.debugEnabled = options.debug || false;
-  }
-
-  log(...args) {
-    if (this.debugEnabled) console.log("[wick-i18n]", ...args);
-  }
-
-  record(key, text, file) {
-    if (this.dictionary.has(key) && this.dictionary.get(key) !== text) {
-      console.warn(
-        `[wick-i18n] Collision in ${file}\nKey: "${key}"\nNew: "${text}"`,
-      );
-      return;
-    }
-    this.dictionary.set(key, text);
-  }
-
-  shouldTranslate(path) {
-    let isIgnored = false;
-    let targetFound = false;
-
-    path.findParent((p) => {
-      if (!p.isJSXElement()) return false;
-
-      const name =
-        p.node.openingElement.name.name ||
-        p.node.openingElement.name.property?.name;
-      const attrs = p.node.openingElement.attributes || [];
-
-      if (
-        attrs.some((a) =>
-          ["data-skip", "data-i18n-skip"].includes(a.name?.name),
-        )
-      ) {
-        isIgnored = true;
-        return true;
-      }
+/**
+ * @fileoverview wick-ui-i18n — Vite plugin that automatically wraps static JSX
+ * text inside Wick UI components with `<WuTranslate>` at build/dev time and
+ * emits a `wick-ui-i18n.json` translation dictionary.
+ *
+ * @example
+ * // vite.config.js
+ * import wickI18n from '@npm-questionpro/wick-ui-i18n';
+ *
+ * export default {
+ *   plugins: [
+ *     wickI18n({
+ *       components: ['MyWidget'],
+ *       ignoreComponents: ['MyRawHtml'],
+ *       debug: true,
+ *     }),
+ *   ],
+ * };
+ */
 
-      if (this.ignoreComponents.has(name)) {
-        isIgnored = true;
-        return true;
-      }
-
-      const hasWrapper = attrs.some(
-        (a) => a.name?.name === "data-i18n-wrapper",
-      );
-      const isTarget = this.components.has(name) || name?.startsWith("Wu");
-      // const isTarget = this.components.has(name);
-
-      if (hasWrapper || isTarget) {
-        targetFound = true;
-        return true;
-      }
-
-      return false;
-    });
-
-    return targetFound && !isIgnored;
-  }
+import { createFilter } from "vite";
+import { TranslationProcessor } from "./src/processor.js";
+import { transformFile } from "./src/transform.js";
+import { printReport } from "./src/debug.js";
+
+/**
+ * @typedef {object} WickI18nOptions
+ * @property {string[]}  [components]        - Extra component names that trigger translation.
+ * @property {string[]}  [ignoreComponents]  - Component names to exclude from translation.
+ * @property {string|string[]|RegExp} [excludeFiles] - Files to skip (passed as `exclude` to Vite's createFilter).
+ * @property {boolean}   [debug]             - Log transform activity to the console.
+ */
+
+/**
+ * Vite plugin factory for wick-ui-i18n.
+ *
+ * @param {WickI18nOptions} [options]
+ * @returns {import('vite').Plugin}
+ */
+export default function wickuiI18nPlugin(options = {}) {
+  const processor = new TranslationProcessor({
+    components: options.components || [],
+    ignoreComponents: options.ignoreComponents,
+    debug: options.debug,
+  });
 
-  getExplicitKey(path) {
-    const parent = path.findParent((p) => p.isJSXElement());
-    const attr = parent?.node.openingElement.attributes.find(
-      (a) => a.name?.name === "data-i18n-key",
-    );
-    if (!attr) return null;
-    return attr.value.type === "StringLiteral"
-      ? attr.value.value
-      : attr.value.expression?.value;
-  }
-}
+  const filter = createFilter([/\.(jsx|tsx)$/], options.excludeFiles);
 
-export default function wickuiI18nPlugin(options = {}) {
-  const processor = new TranslationProcessor(options);
-  const filter = createFilter(options.include || [/\.(jsx|tsx)$/]);
+  let base = "/";
 
   return {
     name: "wick-ui-i18n",
     enforce: "pre",
 
-    transform(code, id) {
-      if (!filter(id) || !code.includes("Wu")) return null;
-
-      const ast = parse(code, {
-        sourceType: "module",
-        plugins: ["jsx", "typescript"],
-      });
-      const ms = new MagicString(code);
-      let [needsImport, hasImport] = [false, false];
-
-      const handleCapture = (path, text, start, end) => {
-        const cleanText = text.trim();
-        if (!cleanText || !processor.shouldTranslate(path)) return;
-
-        const key = processor.getExplicitKey(path) || cleanText;
-        processor.record(key, cleanText, id);
-
-        const original = ms.slice(start, end);
-        ms.overwrite(
-          start,
-          end,
-          `<WuTranslate __i18nKey=${JSON.stringify(key)}></WuTranslate>`,
-        );
-        needsImport = true;
-      };
-
-      traverse(ast, {
-        ImportDeclaration(path) {
-          if (path.node.source.value.includes("wick-ui-lib")) {
-            hasImport = path.node.specifiers.some(
-              (s) => s.imported?.name === "WuTranslate",
-            );
-          }
-        },
-        JSXText(path) {
-          const text = path.node.value;
-          const trimmed = text.trim();
-          const start = path.node.start + text.indexOf(trimmed);
-          handleCapture(path, trimmed, start, start + trimmed.length);
-        },
-        JSXExpressionContainer(path) {
-          const expr = path.node.expression;
-          let text = null;
-          if (expr.type === "StringLiteral") text = expr.value;
-          else if (
-            expr.type === "TemplateLiteral" &&
-            !expr.expressions.length
-          ) {
-            text = expr.quasis[0].value.cooked;
-          }
-          if (text) handleCapture(path, text, path.node.start, path.node.end);
-        },
-      });
-
-      if (needsImport && !hasImport) {
-        ms.prepend(
-          `import { WuTranslate } from '@npm-questionpro/wick-ui-lib';\n`,
-        );
-      }
-
-      return needsImport
-        ? { code: ms.toString(), map: ms.generateMap({ hires: true }) }
-        : null;
+    /**
+     * Capture the resolved base so the dev-server middleware path matches
+     * what `import.meta.env.BASE_URL` resolves to in the consumer app.
+     *
+     * @param {import('vite').ResolvedConfig} resolvedConfig
+     */
+    configResolved(resolvedConfig) {
+      base = resolvedConfig.base;
     },
 
+    /**
+     * Clear state on every build so stale keys don't accumulate across
+     * watch-mode rebuilds.
+     */
     buildStart() {
       processor.dictionary.clear();
+      processor.entries = [];
     },
 
+    /**
+     * Transform a single file: skip fast if it has no "Wu" tokens, then run
+     * the full AST rewrite.
+     *
+     * @param {string} code
+     * @param {string} id
+     */
+    transform(code, id) {
+      if (!filter(id) || (!code.includes("Wu") && !/\bwt\(/.test(code))) return null;
+      return transformFile(code, id, processor);
+    },
+
+    /**
+     * Expose the collected dictionary at `GET /wick-ui-i18n.json` during dev.
+     *
+     * @param {import('vite').ViteDevServer} server
+     */
     configureServer(server) {
-      server.middlewares.use("/wick-ui-i18n.json", (req, res) => {
+      server.middlewares.use(`${base}wick-ui-i18n.json`, (_req, res) => {
         res.setHeader("Content-Type", "application/json");
         res.end(
           JSON.stringify(Object.fromEntries(processor.dictionary), null, 2),
@@ -183,6 +97,7 @@ export default function wickuiI18nPlugin(options = {}) {
       });
     },
 
+    /** Emit the translation dictionary as a build asset and print debug table. */
     generateBundle() {
       this.emitFile({
         type: "asset",
@@ -193,6 +108,8 @@ export default function wickuiI18nPlugin(options = {}) {
           2,
         ),
       });
+
+      printReport(processor.entries);
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npm-questionpro/wick-ui-i18n",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "ISC",
   "description": "Auto-translation AST wrapper for Wick UI",
   "type": "module",

package/src/debug.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Build-time debug reporter — prints a formatted table of every
+ * captured translation entry (text, source file, JSX component tree) to stdout
+ * after the bundle is generated.
+ */
+
+import { basename } from "node:path";
+
+/**
+ * Walk up the Babel path and collect JSX element names from outermost inward.
+ *
+ * @param {import('@babel/traverse').NodePath} path
+ * @returns {string} e.g. `"WuProvider > div > WuButton"`
+ */
+export function getComponentTree(path) {
+  const parts = [];
+  path.findParent((p) => {
+    if (p.isJSXElement()) {
+      const name =
+        p.node.openingElement.name.name ||
+        p.node.openingElement.name.property?.name;
+      if (name) parts.unshift(name);
+    }
+    return false;
+  });
+  return parts.join(" > ") || "(root)";
+}
+
+/**
+ * @typedef {object} DebugEntry
+ * @property {string} key           - i18n key used in WuTranslate.
+ * @property {string} text          - Original source text.
+ * @property {string} file          - Absolute path of the source file.
+ * @property {string} componentTree - Ancestor JSX chain, outermost first.
+ */
+
+/**
+ * Print a box-drawing ASCII table of all captured translation entries.
+ * Columns are auto-sized to content.
+ *
+ * @param {DebugEntry[]} entries
+ */
+export function printReport(entries) {
+  if (!entries.length) {
+    console.log("\n[wick-i18n] No translations captured.\n");
+    return;
+  }
+
+  const headers = ["Text", "File", "Component Tree"];
+
+  const rows = entries.map((e) => [e.text, basename(e.file), e.componentTree]);
+
+  const cols = headers.length;
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => r[i].length)),
+  );
+
+  const pad = (str, w) => str.padEnd(w);
+  const sep = (l, m, r, fill) =>
+    l + widths.map((w) => fill.repeat(w + 2)).join(m) + r;
+
+  const top = sep("┌", "┬", "┐", "─");
+  const mid = sep("├", "┼", "┤", "─");
+  const bottom = sep("└", "┴", "┘", "─");
+  const row = (cells) =>
+    "│" + cells.map((c, i) => ` ${pad(c, widths[i])} `).join("│") + "│";
+
+  const lines = [
+    "",
+    `[wick-i18n] Build report — ${entries.length} translation(s) captured`,
+    top,
+    row(headers),
+    mid,
+    ...rows.map(row),
+    bottom,
+    "",
+  ];
+
+  console.log(lines.join("\n"));
+}

package/src/processor.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview TranslationProcessor — maintains the translation dictionary and
+ * decides which JSX nodes should be wrapped with WuTranslate.
+ */
+
+/** Components always excluded from translation regardless of user config. */
+const DEFAULT_IGNORE = [
+  "WuIcon",
+  "WuTranslateProvider",
+  "WuHelpButton",
+  "WuActivityLog",
+  "WuAppHeader",
+  "WuAPpHeadeMenu",
+  "WuCopyToClipboard",
+  "WuMenuIcon",
+  "WuScrollArea",
+  "WuDrawer",
+  "WuLoader",
+  "WuContentEditor",
+];
+
+export class TranslationProcessor {
+  /**
+   * @param {object} options
+   * @param {string[]} options.components       - Component names that trigger translation.
+   * @param {string[]} [options.ignoreComponents] - Extra components to exclude.
+   * @param {boolean}  [options.debug]           - Enable verbose logging.
+   */
+  constructor(options) {
+    this.components = new Set(options.components);
+    this.ignoreComponents = new Set(
+      DEFAULT_IGNORE.concat(options.ignoreComponents || []),
+    );
+    /** @type {Map<string, string>} key → original text */
+    this.dictionary = new Map();
+    /** @type {import('./debug.js').DebugEntry[]} */
+    this.entries = [];
+    this.debugEnabled = options.debug || false;
+  }
+
+  /**
+   * Conditional logger — only emits when `debug: true`.
+   * @param {...unknown} args
+   */
+  log(...args) {
+    if (this.debugEnabled) console.log("[wick-i18n]", ...args);
+  }
+
+  /**
+   * Store a key→text pair and append a debug entry.
+   * Warns on collision (same key, different text).
+   *
+   * @param {string} key
+   * @param {string} text
+   * @param {string} file           - Source file path.
+   * @param {string} componentTree  - JSX ancestor chain for the debug report.
+   */
+  record(key, text, file, componentTree) {
+    if (this.dictionary.has(key) && this.dictionary.get(key) !== text) {
+      console.warn(
+        `[wick-i18n] Collision in ${file}\nKey: "${key}"\nNew: "${text}"`,
+      );
+      return;
+    }
+    this.dictionary.set(key, text);
+    this.entries.push({ key, text, file, componentTree });
+  }
+
+  /**
+   * Walk up the JSX tree from `path` to determine if the node is inside a
+   * component that should be translated.
+   *
+   * Rules (first match wins, walking outward):
+   *  - `data-skip` / `data-i18n-skip` attr  → ignored
+   *  - component in `ignoreComponents`       → ignored
+   *  - `data-i18n-wrapper` attr OR component starts with "Wu" / is in `components` → translate
+   *
+   * @param {import('@babel/traverse').NodePath} path
+   * @returns {boolean}
+   */
+  shouldTranslate(path) {
+    let isIgnored = false;
+    let targetFound = false;
+
+    path.findParent((p) => {
+      if (!p.isJSXElement()) return false;
+
+      const name =
+        p.node.openingElement.name.name ||
+        p.node.openingElement.name.property?.name;
+      const attrs = p.node.openingElement.attributes || [];
+
+      if (
+        attrs.some((a) =>
+          ["data-skip", "data-i18n-skip"].includes(a.name?.name),
+        )
+      ) {
+        isIgnored = true;
+        return true;
+      }
+
+      if (this.ignoreComponents.has(name)) {
+        isIgnored = true;
+        return true;
+      }
+
+      const hasWrapper = attrs.some(
+        (a) => a.name?.name === "data-i18n-wrapper",
+      );
+      const isTarget = this.components.has(name) || name?.startsWith("Wu");
+
+      if (hasWrapper || isTarget) {
+        targetFound = true;
+        return true;
+      }
+
+      return false;
+    });
+
+    return targetFound && !isIgnored;
+  }
+
+  /**
+   * Return the explicit i18n key from the nearest ancestor JSX element's
+   * `data-i18n-key` attribute, or `null` if absent.
+   *
+   * @param {import('@babel/traverse').NodePath} path
+   * @returns {string|null}
+   */
+  getExplicitKey(path) {
+    let result = null;
+    path.findParent((p) => {
+      if (!p.isJSXElement()) return false;
+      const attr = p.node.openingElement.attributes.find(
+        (a) => a.name?.name === "data-i18n-key",
+      );
+      if (!attr) return false;
+      const val =
+        attr.value.type === "StringLiteral"
+          ? attr.value.value
+          : attr.value.expression?.value;
+      if (!val) {
+        console.warn(
+          `[wick-i18n] data-i18n-key on <${p.node.openingElement.name.name}> is dynamic or empty — falling back to text content.`,
+        );
+        return true;
+      }
+      result = val;
+      return true;
+    });
+    return result;
+  }
+}