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

package/src/transform.js

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview AST transform — parses a JSX/TSX file, rewrites translatable
+ * text nodes to `<WuTranslate>`, and prepends the import if needed.
+ */
+
+import MagicString from "magic-string";
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import { getComponentTree } from "./debug.js";
+import { transformTemplateLiteralExpression } from "./transformTemplateLiteral.js";
+import { transformJSXTextWithEntities } from "./transformJSXTextWithEntities.js";
+import { recordWtCall, transformWtTemplateLiteral } from "./transformWtCalls.js";
+
+const traverse = _traverse.default || _traverse;
+
+/** Babel parser plugins applied to every file. */
+const BABEL_PLUGINS = ["jsx", "typescript"];
+
+/**
+ * Matches any HTML entity: named (&amp;), decimal (&#169;), or hex (&#x00A9;).
+ * Used to skip text segments that contain entities — they must be left as-is.
+ * Note: for JSXText this must be tested against the RAW source, not the Babel
+ * decoded .value (Babel turns &amp; → "&", &nbsp; → "\u00a0", etc.).
+ */
+const HTML_ENTITY_RE = /&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);/;
+
+/** @param {import('@babel/types').Node} node @returns {string|null} */
+function getStaticString(node) {
+  if (node.type === "StringLiteral") return node.value;
+  if (node.type === "TemplateLiteral" && !node.expressions.length)
+    return node.quasis[0].value.cooked;
+  return null;
+}
+
+/**
+ * Replace a translatable text node with a `<WuTranslate>` element and record
+ * the key in the processor's dictionary.
+ *
+ * @param {import('@babel/traverse').NodePath} path  - Path of the text node.
+ * @param {string}       text       - Trimmed text content.
+ * @param {number}       start      - Absolute start offset in source.
+ * @param {number}       end        - Absolute end offset in source.
+ * @param {MagicString}  ms         - Mutable source string.
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string}       id         - File path (for collision warnings).
+ * @returns {boolean} `true` when replacement was made.
+ */
+function handleCapture(path, text, start, end, ms, processor, id, skipExplicitKey = false) {
+  const cleanText = text.trim().replace(/\n/g, " ").replace(/\s{2,}/g, " ");
+  if (!cleanText || !processor.shouldTranslate(path)) return false;
+  // For StringLiteral / TemplateLiteral quasis / ternary branches: entities are
+  // not decoded by the JS parser, so cleanText still contains "&amp;" etc.
+  if (HTML_ENTITY_RE.test(cleanText)) return false;
+
+  const key = (!skipExplicitKey && processor.getExplicitKey(path)) || cleanText;
+  processor.record(key, cleanText, id, getComponentTree(path));
+
+  ms.overwrite(
+    start,
+    end,
+    `<WuTranslate __i18nKey=${JSON.stringify(key)}></WuTranslate>`,
+  );
+  return true;
+}
+
+/**
+ * Parse `code`, replace all translatable JSX text nodes, and prepend the
+ * `WuTranslate` import when necessary.
+ *
+ * @param {string} code - Raw source of the file.
+ * @param {string} id   - File path.
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @returns {{ code: string, map: object } | null} Transformed result, or
+ *   `null` when no changes were made.
+ */
+export function transformFile(code, id, processor) {
+  const ast = parse(code, {
+    sourceType: "module",
+    plugins: BABEL_PLUGINS,
+  });
+
+  const ms = new MagicString(code);
+  let needsImport = false;
+  let hasImport = false;
+  let hasWtTransform = false;
+
+  traverse(ast, {
+    /**
+     * Track whether `WuTranslate` is already imported from wick-ui-lib so we
+     * don't duplicate the import statement.
+     */
+    /**
+     * wt("static string") call — record the key in the dictionary.
+     * No code transformation; wt() handles runtime lookup.
+     */
+    CallExpression(path) {
+      if (recordWtCall(path, processor, id)) return;
+      if (transformWtTemplateLiteral(path, code, ms, processor, id)) {
+        hasWtTransform = true;
+      }
+    },
+
+    ImportDeclaration(path) {
+      if (path.node.source.value.includes("wick-ui-lib")) {
+        hasImport = path.node.specifiers.some(
+          (s) => s.imported?.name === "WuTranslate",
+        );
+      }
+    },
+
+    /** Plain JSX text: `<Foo>Hello world</Foo>` */
+    JSXText(path) {
+      const text = path.node.value;
+      const trimmed = text.trim();
+      // Babel decodes entities in JSXText.value (&amp; → "&", &#169; → "©").
+      // Check the raw source slice — if entities found, split around them so
+      // translatable text segments are still wrapped while entities stay put.
+      const rawSource = code.slice(path.node.start, path.node.end);
+      if (HTML_ENTITY_RE.test(rawSource)) {
+        if (transformJSXTextWithEntities(path, rawSource, ms, processor, id)) {
+          needsImport = true;
+        }
+        return;
+      }
+      const start = path.node.start + text.indexOf(trimmed);
+      if (
+        handleCapture(
+          path,
+          trimmed,
+          start,
+          start + trimmed.length,
+          ms,
+          processor,
+          id,
+        )
+      ) {
+        needsImport = true;
+      }
+    },
+
+    /**
+     * JSX expression containers with a static string value:
+     *   `<Foo>{"Hello"}</Foo>`  or  `<Foo>{\`Hello\`}</Foo>`
+     *
+     * Attribute values (`variant={'secondary'}`) are skipped — their parent is
+     * a JSXAttribute, not a JSXElement child position.
+     */
+    JSXExpressionContainer(path) {
+      if (path.parent.type === "JSXAttribute") return;
+
+      const expr = path.node.expression;
+      let text = null;
+
+      if (expr.type === "StringLiteral") {
+        text = expr.value;
+      } else if (
+        expr.type === "TemplateLiteral" &&
+        expr.expressions.length > 0
+      ) {
+        if (
+          transformTemplateLiteralExpression(path, code, ms, processor, id)
+        ) {
+          needsImport = true;
+        }
+        return;
+      } else if (expr.type === "TemplateLiteral" && !expr.expressions.length) {
+        text = expr.quasis[0].value.cooked;
+      } else if (expr.type === "ConditionalExpression") {
+        const consText = getStaticString(expr.consequent);
+        const altText = getStaticString(expr.alternate);
+        let changed = false;
+        if (consText !== null)
+          changed =
+            handleCapture(
+              path,
+              consText,
+              expr.consequent.start,
+              expr.consequent.end,
+              ms,
+              processor,
+              id,
+              true,
+            ) || changed;
+        if (altText !== null)
+          changed =
+            handleCapture(
+              path,
+              altText,
+              expr.alternate.start,
+              expr.alternate.end,
+              ms,
+              processor,
+              id,
+              true,
+            ) || changed;
+        if (changed) needsImport = true;
+        return;
+      }
+
+      if (
+        text &&
+        handleCapture(
+          path,
+          text,
+          path.node.start,
+          path.node.end,
+          ms,
+          processor,
+          id,
+        )
+      ) {
+        needsImport = true;
+      }
+    },
+  });
+
+  if (!needsImport && !hasWtTransform) return null;
+
+  if (!hasImport) {
+    ms.prepend(`import { WuTranslate } from '@npm-questionpro/wick-ui-lib';\n`);
+  }
+
+  return { code: ms.toString(), map: ms.generateMap({ hires: true }) };
+}

package/src/transformJSXTextWithEntities.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview transformJSXTextWithEntities — splits a JSXText node that
+ * contains HTML entities into interleaved translated segments and raw entities.
+ *
+ * @example
+ * // Input
+ * <WuButton>Hello &amp; World</WuButton>
+ *
+ * // Output
+ * <WuButton><WuTranslate __i18nKey="Hello" /> &amp; <WuTranslate __i18nKey="World" /></WuButton>
+ *
+ * @example
+ * // Input
+ * <WuButton>&lt;Tag&gt;</WuButton>
+ *
+ * // Output
+ * <WuButton>&lt;<WuTranslate __i18nKey="Tag" />&gt;</WuButton>
+ */
+
+import { getComponentTree } from "./debug.js";
+
+/**
+ * Splits the raw source around HTML entities (capturing group keeps entities
+ * in the resulting array).
+ *
+ * "Hello &amp; World"  →  ["Hello ", "&amp;", " World"]
+ * "&lt;Tag&gt;"        →  ["", "&lt;", "Tag", "&gt;", ""]
+ */
+const HTML_ENTITY_SPLIT_RE =
+  /(&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);)/g;
+
+/**
+ * Tests whether a single segment (from the split above) is itself an entity.
+ */
+const HTML_ENTITY_SEGMENT_RE =
+  /^&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);$/;
+
+/**
+ * Given a text segment, extract leading whitespace, the translatable core,
+ * and trailing whitespace so spacing around entities is preserved.
+ *
+ * @param {string} raw
+ * @returns {{ leading: string, text: string, trailing: string }}
+ */
+function splitSegment(raw) {
+  const leading = raw.match(/^\s*/)[0];
+  const trailing = raw.match(/\s*$/)[0];
+  // Normalise internal whitespace to match handleCapture behaviour:
+  // newlines → single space, consecutive spaces → single space.
+  const text = raw
+    .slice(leading.length, raw.length - trailing.length)
+    .replace(/\n/g, " ")
+    .replace(/\s{2,}/g, " ");
+  return { leading, text, trailing };
+}
+
+/**
+ * Transform a JSXText node whose raw source contains at least one HTML entity.
+ *
+ * Each non-entity text segment is independently trimmed and wrapped in a
+ * `<WuTranslate>` element. Entities are emitted verbatim. Leading / trailing
+ * whitespace within each segment is preserved as JSX text so words don't run
+ * together after the replacement.
+ *
+ * If every segment is either empty or a bare entity (no translatable text),
+ * the node is left untouched and the function returns `false`.
+ *
+ * @param {import('@babel/traverse').NodePath} path  - JSXText path.
+ * @param {string}      rawSource  - Raw source slice for this node
+ *                                   (code.slice(node.start, node.end)).
+ * @param {import('magic-string').default} ms
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string}      id         - Source file path (for collision warnings).
+ * @returns {boolean} `true` when a replacement was written.
+ */
+export function transformJSXTextWithEntities(
+  path,
+  rawSource,
+  ms,
+  processor,
+  id,
+) {
+  if (!processor.shouldTranslate(path)) return false;
+
+  // data-i18n-key cannot span multiple split segments — warn and ignore it.
+  const explicitKey = processor.getExplicitKey(path);
+  if (explicitKey) {
+    console.warn(
+      `[wick-i18n] data-i18n-key="${explicitKey}" is set on a node whose text ` +
+        `contains HTML entities. The key cannot apply across multiple segments ` +
+        `— splitting without it.`,
+    );
+  }
+
+  const segments = rawSource.split(HTML_ENTITY_SPLIT_RE);
+  const componentTree = getComponentTree(path);
+
+  const parts = [];
+  let hasTranslatable = false;
+
+  for (const seg of segments) {
+    if (!seg) continue; // empty strings produced by split at boundaries
+
+    if (HTML_ENTITY_SEGMENT_RE.test(seg)) {
+      // Raw entity — emit as-is, no translation key
+      parts.push(seg);
+    } else {
+      const { leading, text, trailing } = splitSegment(seg);
+
+      if (text) {
+        processor.record(text, text, id, componentTree);
+        parts.push(
+          `${leading}<WuTranslate __i18nKey=${JSON.stringify(text)}></WuTranslate>${trailing}`,
+        );
+        hasTranslatable = true;
+      } else {
+        // Pure whitespace between / around entities — preserve as JSX text
+        parts.push(seg);
+      }
+    }
+  }
+
+  if (!hasTranslatable) return false;
+
+  ms.overwrite(path.node.start, path.node.end, parts.join(""));
+  return true;
+}

package/src/transformTemplateLiteral.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview transformTemplateLiteral — handles JSXExpressionContainers
+ * whose expression is a TemplateLiteral with one or more dynamic expressions.
+ *
+ * @example
+ * // Input
+ * <WuButton>{`hello ${name} how are you`}</WuButton>
+ *
+ * // Output
+ * <WuButton><><WuTranslate __i18nKey="hello" /> {name} <WuTranslate __i18nKey="how are you" /></></WuButton>
+ */
+
+import { getComponentTree } from "./debug.js";
+
+/**
+ * Given a quasi's cooked string, extract leading whitespace, trimmed text,
+ * and trailing whitespace as separate pieces so spacing is preserved in the
+ * reconstructed JSX fragment.
+ *
+ * @param {string} raw - The cooked value of a TemplateElement.
+ * @returns {{ leading: string, text: string, trailing: string }}
+ */
+function splitQuasi(raw) {
+  const leading = raw.match(/^\s*/)[0];
+  const trailing = raw.match(/\s*$/)[0];
+  const text = raw.slice(leading.length, raw.length - trailing.length);
+  return { leading, text, trailing };
+}
+
+/**
+ * Transform a JSXExpressionContainer whose expression is a TemplateLiteral
+ * with one or more dynamic expressions into an interleaved React fragment:
+ *
+ *   {`hello ${name} how are you`}
+ *   → <><WuTranslate __i18nKey="hello" /> {name} <WuTranslate __i18nKey="how are you" /></>
+ *
+ * Quasis that are empty or whitespace-only are skipped (no key emitted).
+ * Leading/trailing whitespace within a quasi is preserved as JSX text around
+ * the WuTranslate element so words don't run together after translation.
+ *
+ * @param {import('@babel/traverse').NodePath} path  - JSXExpressionContainer path.
+ * @param {string}      code       - Original source (used to slice expression text).
+ * @param {import('magic-string').default} ms
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string}      id         - Source file path (for collision warnings).
+ * @returns {boolean} `true` when a replacement was written.
+ */
+export function transformTemplateLiteralExpression(
+  path,
+  code,
+  ms,
+  processor,
+  id,
+) {
+  if (!processor.shouldTranslate(path)) return false;
+
+  const container = path.node;
+  const expr = container.expression; // TemplateLiteral
+  const { quasis, expressions } = expr;
+  const componentTree = getComponentTree(path);
+
+  const parts = [];
+  let hasTranslatable = false;
+
+  for (let i = 0; i < quasis.length; i++) {
+    const cooked = quasis[i].value.cooked ?? quasis[i].value.raw;
+    const { leading, text, trailing } = splitQuasi(cooked);
+
+    if (text) {
+      processor.record(text, text, id, componentTree);
+      parts.push(
+        `${leading}<WuTranslate __i18nKey=${JSON.stringify(text)}></WuTranslate>${trailing}`,
+      );
+      hasTranslatable = true;
+    }
+    // whitespace-only or empty quasi — emit nothing (no key, no node)
+
+    // Interleave: expression follows its preceding quasi (skip after last quasi)
+    if (i < expressions.length) {
+      const exprNode = expressions[i];
+      parts.push(`{${code.slice(exprNode.start, exprNode.end)}}`);
+    }
+  }
+
+  if (!hasTranslatable) return false;
+
+  // Replace the entire {`...`} container with a React fragment
+  ms.overwrite(container.start, container.end, `<>${parts.join("")}</>`);
+  return true;
+}

package/src/transformWtCalls.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview transformWtCalls — detects wt("static string") call expressions
+ * and records the argument as a translation key.
+ *
+ * No code transformation is performed. wt() handles runtime lookup via the
+ * dictionary loaded by WuTranslateProvider. The plugin's only job here is to
+ * ensure static arguments appear in wick-ui-i18n.json at build time so they
+ * reach the translation API.
+ *
+ * Supported argument forms:
+ *   wt("hello")         — StringLiteral
+ *   wt(`hello`)         — TemplateLiteral with zero expressions
+ *
+ * Ignored:
+ *   wt(variable)        — dynamic, cannot be statically analysed
+ *   wt(`hello ${name}`) — has expressions, not fully static
+ *   wt()  /  wt(a, b)   — wrong arity
+ */
+
+/**
+ * Extract leading whitespace, normalised text, and trailing whitespace from a
+ * template quasi string. Mirrors the normalisation applied everywhere else in
+ * the plugin (newlines → space, consecutive spaces → one space).
+ *
+ * @param {string} raw
+ * @returns {{ leading: string, text: string, trailing: string }}
+ */
+function splitQuasi(raw) {
+  const leading = raw.match(/^\s*/)[0];
+  const trailing = raw.match(/\s*$/)[0];
+  const text = raw
+    .slice(leading.length, raw.length - trailing.length)
+    .replace(/\n/g, " ")
+    .replace(/\s{2,}/g, " ");
+  return {leading, text, trailing};
+}
+
+/**
+ * If `path` is a `wt(staticString)` call expression, record the key in the
+ * processor dictionary. Returns `true` when a key was recorded.
+ *
+ * @param {import('@babel/traverse').NodePath} path  - CallExpression path.
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string} id - Source file path (for collision warnings).
+ * @returns {boolean}
+ */
+export function recordWtCall(path, processor, id) {
+  const { callee, arguments: args } = path.node;
+
+  // Only handle bare `wt(...)` identifiers — not obj.wt(...) etc.
+  if (callee.type !== "Identifier" || callee.name !== "wt") return false;
+  if (args.length !== 1) return false;
+
+  const arg = args[0];
+  let text = null;
+
+  if (arg.type === "StringLiteral") {
+    text = arg.value;
+  } else if (arg.type === "TemplateLiteral" && arg.expressions.length === 0) {
+    text = arg.quasis[0].value.cooked ?? arg.quasis[0].value.raw;
+  }
+
+  if (text === null) return false;
+
+  const cleanText = text
+    .trim()
+    .replace(/\n/g, " ")
+    .replace(/\s{2,}/g, " ");
+  if (!cleanText) return false;
+
+  processor.record(cleanText, cleanText, id, "(wt)");
+  return true;
+}
+
+/**
+ * Transform a `wt(\`template ${expr} literal\`)` call whose template has one
+ * or more dynamic expressions.
+ *
+ * Each static quasi is independently extracted and replaced with a nested
+ * `wt("text")` call; dynamic expressions are preserved in place. The whole
+ * `wt(\`...\`)` call is replaced with a plain template literal:
+ *
+ *   wt(`Hello ${name}`)        →  `${wt("Hello")} ${name}`
+ *   wt(`${a} and ${b}`)        →  `${a} ${wt("and")} ${b}`
+ *   wt(`Hello ${a} and ${b}`)  →  `${wt("Hello")} ${a} ${wt("and")} ${b}`
+ *
+ * If no quasi contains translatable text, the call is left untouched and the
+ * function returns `false`.
+ *
+ * @param {import('@babel/traverse').NodePath} path - CallExpression path.
+ * @param {string}      code   - Original source (for slicing expression text).
+ * @param {import('magic-string').default} ms
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string}      id     - Source file path.
+ * @returns {boolean} `true` when the call was rewritten.
+ */
+export function transformWtTemplateLiteral(path, code, ms, processor, id) {
+  const {callee, arguments: args} = path.node;
+
+  if (callee.type !== "Identifier" || callee.name !== "wt") return false;
+  if (args.length !== 1) return false;
+
+  const arg = args[0];
+  if (arg.type !== "TemplateLiteral" || arg.expressions.length === 0)
+    return false;
+
+  const {quasis, expressions} = arg;
+  const parts = ["`"];
+  let hasTranslatable = false;
+
+  for (let i = 0; i < quasis.length; i++) {
+    const cooked = quasis[i].value.cooked ?? quasis[i].value.raw;
+    const {leading, text, trailing} = splitQuasi(cooked);
+
+    if (text) {
+      processor.record(text, text, id, "(wt)");
+      parts.push(`${leading}\${wt(${JSON.stringify(text)})}${trailing}`);
+      hasTranslatable = true;
+    } else {
+      // empty or whitespace-only quasi — preserve as literal template text
+      parts.push(cooked);
+    }
+
+    if (i < expressions.length) {
+      const exprSrc = code.slice(expressions[i].start, expressions[i].end);
+      parts.push(`\${${exprSrc}}`);
+    }
+  }
+
+  parts.push("`");
+
+  if (!hasTranslatable) return false;
+
+  ms.overwrite(path.node.start, path.node.end, parts.join(""));
+  return true;
+}