@npm-questionpro/wick-ui-i18n 2.0.0-next.29 → 2.0.0-next.31

package/README.md

@@ -1,104 +1,52 @@
 # wick-ui-i18n
 
-Vite plugin — wraps JSX text in Wu components with `<WuTranslate>`, rewrites translatable props to `{wt("...")}`, and
-emits `wick-ui-i18n.json`.
+Vite plugin — wraps JSX text in Wu\* components with `<WuTranslate>`, rewrites translatable props to `{useWt()("...")}`,
+records `wt()` / `useWt()()` calls, and emits `wick-ui-i18n.json`.
 
----
-
-## JSX text
-
-| Input                                          | Output                                                                         |
-| ---------------------------------------------- | ------------------------------------------------------------------------------ |
-| `<WuButton>Hello</WuButton>`                   | ✅ `<WuTranslate __i18nKey="Hello" />`                                         |
-| `<WuIcon>star</WuIcon>`                        | ❌                                                                             |
-| `<div>Hello</div>`                             | ❌                                                                             |
-| `<WuButton data-skip>Hello</WuButton>`         | ❌                                                                             |
-| `<span data-i18n-wrapper>Hello</span>`         | ✅ `<WuTranslate __i18nKey="Hello" />`                                         |
-| `<WuButton data-i18n-key="k">Hello</WuButton>` | ✅ `<WuTranslate __i18nKey="k" />`                                             |
-| `<WuButton>&amp;</WuButton>`                   | ❌                                                                             |
-| `<WuButton>Hello &amp; World</WuButton>`       | ✅ `<WuTranslate __i18nKey="Hello" /> &amp; <WuTranslate __i18nKey="World" />` |
-
-## JSX string expressions
-
-| Input                              | Output                                 |
-| ---------------------------------- | -------------------------------------- |
-| `<WuButton>{"Hello"}</WuButton>`   | ✅ `<WuTranslate __i18nKey="Hello" />` |
-| ``<WuButton>{`Hello`}</WuButton>`` | ✅ `<WuTranslate __i18nKey="Hello" />` |
-| `<WuButton>{variable}</WuButton>`  | ❌                                     |
-
-## JSX ternaries
-
-| Input                                               | Output                                                                                                       |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `<WuButton>{flag ? "Yes" : "No"}</WuButton>`        | ✅ `{flag ? <WuTranslate __i18nKey="Yes" /> : <WuTranslate __i18nKey="No" />}`                               |
-| `<WuButton>{flag ? "Yes" : variable}</WuButton>`    | ✅ `{flag ? <WuTranslate __i18nKey="Yes" /> : variable}`                                                     |
-| `<WuButton>{flag ? variable : variable}</WuButton>` | ❌                                                                                                           |
-| `<WuButton>{a ? "A" : b ? "B" : "C"}</WuButton>`    | ✅ `{a ? <WuTranslate __i18nKey="A" /> : b ? <WuTranslate __i18nKey="B" /> : <WuTranslate __i18nKey="C" />}` |
-
-## JSX template literals with expressions
+> Full docs and examples: Storybook → **i18n/Overview**
 
-| Input                                            | Output                                                                              |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| ``<WuButton>{`Hello ${name}`}</WuButton>``       | ✅ `<><WuTranslate __i18nKey="Hello" /> {name}</>`                                  |
-| ``<WuButton>{`${name} world`}</WuButton>``       | ✅ `<>{name} <WuTranslate __i18nKey="world" /></>`                                  |
-| ``<WuButton>{`Hello ${a} and ${b}`}</WuButton>`` | ✅ `<><WuTranslate __i18nKey="Hello" /> {a} <WuTranslate __i18nKey="and" /> {b}</>` |
-| ``<WuButton>{`${a}${b}`}</WuButton>``            | ❌                                                                                  |
-
-## JSX mixed children
-
-| Input                               | Output                                        |
-| ----------------------------------- | --------------------------------------------- |
-| `<WuButton>Hello {name}</WuButton>` | ✅ `<WuTranslate __i18nKey="Hello" /> {name}` |
-| `<WuButton>{a} and {b}</WuButton>`  | ✅ `{a} <WuTranslate __i18nKey="and" /> {b}`  |
-| `<WuButton>{a}   {b}</WuButton>`    | ❌                                            |
+---
 
-## JSX props
+## Quick start
 
-Defaults: `Label`, `placeholder`, `title`, `aria-label`, `aria-placeholder`.
+```ts
+// vite.config.ts
+import wickI18n from '@npm-questionpro/wick-ui-i18n'
+export default defineConfig({plugins: [react(), wickI18n()]})
+```
 
-| Input                                  | Output                              |
-| -------------------------------------- | ----------------------------------- |
-| `<WuField Label="First name" />`       | ✅ `Label={wt("First name")}`       |
-| `<WuInput placeholder="Enter name" />` | ✅ `placeholder={wt("Enter name")}` |
-| `<WuDialog title="Confirm?" />`        | ✅ `title={wt("Confirm?")}`         |
-| `<WuField Label={variable} />`         | ❌                                  |
-| `<WuField Label="" />`                 | ❌                                  |
-| `<WuIcon Label="x" />`                 | ❌                                  |
-| `<input placeholder="x" />`            | ❌                                  |
-| `<WuField data-skip Label="x" />`      | ❌                                  |
+---
 
-## `wt()` calls
+## What it transforms
 
-Plugin records static args into `wick-ui-i18n.json`. No code rewrite unless template literal with expressions.
+| Source                                    | Output                                        |
+| ----------------------------------------- | --------------------------------------------- |
+| `<WuButton>Save</WuButton>`               | `<WuTranslate __i18nKey="Save" />`            |
+| `<WuInput Label="First name" />`          | `Label={useWt()("First name")}`               |
+| ``<WuButton>{`${n} results`}</WuButton>`` | `<><WuTranslate __i18nKey="results" />{n}</>` |
+| `wt("Hello")`                             | recorded in dictionary                        |
+| ``wt(`Hello ${name}`)``                   | `` `${wt("Hello")} ${name}` ``                |
+| `useWt()("Hello")`                        | recorded in dictionary                        |
+| ``useWt()(`Hello ${name}`)``              | `` `${useWt()("Hello")} ${name}` ``           |
 
-| Input                         | Dictionary            | Code output                                   |
-| ----------------------------- | --------------------- | --------------------------------------------- |
-| `wt("Hello")`                 | ✅ `"Hello"`          | `wt("Hello")`                                 |
-| ``wt(`Hello`)``               | ✅ `"Hello"`          | ``wt(`Hello`)``                               |
-| ``wt(`Hello ${name}`)``       | ✅ `"Hello"`          | `` `${wt("Hello")} ${name}` ``                |
-| ``wt(`Hello ${a} and ${b}`)`` | ✅ `"Hello"`, `"and"` | `` `${wt("Hello")} ${a} ${wt("and")} ${b}` `` |
-| `wt(variable)`                | ❌                    | —                                             |
-| ``wt(`${a}${b}`)``            | ❌                    | —                                             |
+---
 
-## Data files (`extractFromKeys` option)
+## Options
 
-No code rewrite — keys only recorded in `wick-ui-i18n.json`.
+| Option              | Default                                                           | Description                                                          |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `components`        | `[]`                                                              | Extra components treated like Wu\*                                   |
+| `ignoreComponents`  | `[]`                                                              | Extra components never translated                                    |
+| `translatableProps` | `['Label','placeholder','title','aria-label','aria-placeholder']` | Props rewritten to `useWt()()`                                       |
+| `dataLabelKeys`     | `[]`                                                              | Property names whose values are labels in mixed data files           |
+| `dictionaryFiles`   | —                                                                 | Files where every string is a display label (enums, label constants) |
+| `excludeFiles`      | —                                                                 | Files skipped entirely                                               |
+| `debug`             | `false`                                                           | Print extraction table at build                                      |
 
-| Input                                                   | Dictionary       |
-| ------------------------------------------------------- | ---------------- |
-| `{ label: 'Analytics' }` + `extractFromKeys: ['label']` | ✅ `"Analytics"` |
-| `{ label: variable }`                                   | ❌               |
-| `{ label: '' }`                                         | ❌               |
+> **Deprecated:** `extractFromKeys` → `dataLabelKeys` · `resolveFiles` → `dictionaryFiles`
 
 ---
 
-## Options
+## Breaking changes
 
-| Option              | Default                                                           | Description                           |
-| ------------------- | ----------------------------------------------------------------- | ------------------------------------- |
-| `components`        | `[]`                                                              | Extra components treated like Wu\*    |
-| `ignoreComponents`  | `[]`                                                              | Extra components never translated     |
-| `translatableProps` | `['Label','placeholder','title','aria-label','aria-placeholder']` | Props rewritten to `wt()`             |
-| `extractFromKeys`   | `[]`                                                              | Object keys extracted into dictionary |
-| `excludeFiles`      | —                                                                 | Files skipped entirely                |
-| `debug`             | `false`                                                           | Log transforms to console             |
+See [`BREAKING_CHANGES.md`](./BREAKING_CHANGES.md).

package/index.d.ts

@@ -5,34 +5,72 @@ export interface WickI18nOptions {
   /** Extra component names to translate (in addition to Wu* components). */
   components?: string[]
 
-  /** Component names to exclude from translation. */
+  /** Component names to exclude from translation (extends the built-in ignore list). */
   ignoreComponents?: string[]
 
   /**
-   * JSX prop names rewritten to `{wt("...")}` on Wu* components.
-   * @default ['Label', 'placeholder', 'title', 'aria-label', 'aria-placeholder']
+   * Extra JSX prop names rewritten to `{useWt()("...")}` on Wu* components.
+   * Appended to the defaults — defaults are always kept:
+   * `['Label', 'placeholder', 'title', 'aria-label', 'aria-placeholder']`.
    */
   translatableProps?: string[]
 
   /**
    * Object property names whose string values are extracted into
-   * `wick-ui-i18n.json` without rewriting code. Use for data files
-   * (nav items, option lists, etc.) paired with `wt(item.label)` at render time.
+   * `wick-ui-i18n.json` without rewriting code.
+   *
+   * Use for mixed data files (nav items, option lists, table configs) where
+   * only specific property names hold display labels — icon names, routes, and
+   * IDs with other key names are left alone.
+   *
+   * At render time, look up values with `wt(item.label)`.
+   *
+   * @example
+   * dataLabelKeys: ['label', 'title']
+   * // { key: 'analytics', label: 'Analytics', icon: 'wm-analytics' }
+   * //                            ^^^^^^^^^^^ extracted, icon name ignored
    */
-  extractFromKeys?: string[]
+  dataLabelKeys?: string[]
+
+  /**
+   * Files where **every** string value is a display label — object properties
+   * and TypeScript enum members are all extracted into `wick-ui-i18n.json`.
+   *
+   * Use **only** for dedicated enum/constant files. Do NOT point at mixed data
+   * files — use `dataLabelKeys` for those.
+   *
+   * Passed to Vite's `createFilter` as `include`, so globs, regexes, and
+   * package specifiers all work.
+   *
+   * @example
+   * dictionaryFiles: ['src/enums/*.ts', 'src/constants/labels.ts']
+   */
+  dictionaryFiles?: string | RegExp | Array<string | RegExp>
 
   /** Files to skip entirely. Passed to Vite's `createFilter` as `exclude`. */
   excludeFiles?: string | RegExp | Array<string | RegExp>
 
-  /** Log every transform to the console. */
+  /** Print a build-time extraction report table to stdout. */
   debug?: boolean
+
+  /**
+   * @deprecated Use `dataLabelKeys` instead.
+   */
+  extractFromKeys?: string[]
+
+  /**
+   * @deprecated Use `dictionaryFiles` instead.
+   */
+  resolveFiles?: string | RegExp | Array<string | RegExp>
 }
 
 /**
  * Vite plugin that automatically translates Wick UI components.
  *
  * - JSX text content inside Wu* → `<WuTranslate __i18nKey="..." />`
- * - Translatable props (placeholder, title, Label, …) → `{wt("...")}`
- * - Emits `wick-ui-i18n.json` with all extracted keys
+ * - Translatable props (`Label`, `placeholder`, `title`, …) → `{useWt()("...")}`
+ * - `wt("literal")` and `useWt()("literal")` calls → keys recorded in dictionary
+ * - `wt(\`Hello ${name}\`)` and `useWt()(\`Hello ${name}\`)` → each static quasi extracted and rewritten
+ * - Emits `wick-ui-i18n.json` at build time / serves it at `GET /wick-ui-i18n.json` in dev
  */
 export default function wickuiI18nPlugin(options?: WickI18nOptions): Plugin

package/index.js

@@ -22,14 +22,23 @@ import {createFilter} from 'vite'
 import {TranslationProcessor} from './src/processor.js'
 import {transformFile} from './src/transform.js'
 import {printReport} from './src/debug.js'
+import {TelemetryCollector} from './src/telemetry.js'
+import {extractStringsFromFile} from './src/extractStrings.js'
 
 /**
  * @typedef {object} WickI18nOptions
  * @property {string[]}  [components]        - Extra component names that trigger translation.
  * @property {string[]}  [ignoreComponents]  - Component names to exclude from translation.
- * @property {string[]}  [translatableProps] - JSX prop names rewritten to `{wt("...")}`. Defaults to `['Label','placeholder','title','aria-label','aria-placeholder']`.
- * @property {string[]}  [extractFromKeys]   - Object property names whose string values are extracted as translation keys (e.g. ['label']).
- * @property {string|string[]|RegExp} [excludeFiles] - Files to skip (passed as `exclude` to Vite's createFilter).
+ * @property {string[]}  [translatableProps] - JSX prop names rewritten to `{useWt()("...")}`. Defaults to `['Label','placeholder','title','aria-label','aria-placeholder']`.
+ * @property {string[]}  [dataLabelKeys]     - Object property names whose string values are labels in mixed data
+ *                                             files (e.g. `['label', 'title']` in nav config arrays). No code rewrite;
+ *                                             keys are recorded into `wick-ui-i18n.json` for the translation API.
+ * @property {string[]}  [extractFromKeys]   - @deprecated Use `dataLabelKeys` instead.
+ * @property {string|string[]|RegExp} [dictionaryFiles] - Files where every string is a display label (enum files,
+ *                                             message constants). Pattern: `'**\/enums\/*.ts'`.
+ *                                             Do NOT point at mixed data files — use `dataLabelKeys` for those.
+ * @property {string|string[]|RegExp} [resolveFiles]   - @deprecated Use `dictionaryFiles` instead.
+ * @property {string|string[]|RegExp} [excludeFiles]   - Files to skip (passed as `exclude` to Vite's createFilter).
  * @property {boolean}   [debug]             - Log transform activity to the console.
  */
 
@@ -40,15 +49,22 @@ import {printReport} from './src/debug.js'
  * @returns {import('vite').Plugin}
  */
 export default function wickuiI18nPlugin(options = {}) {
+  const telemetry = new TelemetryCollector()
+
   const processor = new TranslationProcessor({
     components: options.components || [],
     ignoreComponents: options.ignoreComponents,
     translatableProps: options.translatableProps,
-    extractFromKeys: options.extractFromKeys,
+    dataLabelKeys: options.dataLabelKeys,
+    extractFromKeys: options.extractFromKeys, // deprecated alias — processor handles both
     debug: options.debug,
   })
 
   const filter = createFilter([/\.(jsx|tsx|ts)$/], options.excludeFiles)
+  const enumFilter =
+    (options.dictionaryFiles ?? options.resolveFiles)
+      ? createFilter(options.dictionaryFiles ?? options.resolveFiles)
+      : null
 
   let base = '/'
 
@@ -64,6 +80,7 @@ export default function wickuiI18nPlugin(options = {}) {
      */
     configResolved(resolvedConfig) {
       base = resolvedConfig.base
+      telemetry.scanVersions(resolvedConfig.root)
     },
 
     /**
@@ -73,6 +90,7 @@ export default function wickuiI18nPlugin(options = {}) {
     buildStart() {
       processor.dictionary.clear()
       processor.entries = []
+      telemetry.reset()
     },
 
     /**
@@ -83,13 +101,16 @@ export default function wickuiI18nPlugin(options = {}) {
      * @param {string} id
      */
     transform(code, id) {
+      if (enumFilter?.(id)) extractStringsFromFile(code, id, processor)
+
       const hasAnyTarget =
         code.includes('Wu') ||
-        /\bwt\(/.test(code) ||
+        /\bwt\(|useWt\(/.test(code) ||
         (processor.components.size > 0 && [...processor.components].some(c => code.includes(c))) ||
         (processor.extractFromKeys.size > 0 && [...processor.extractFromKeys].some(k => code.includes(k)))
       if (!filter(id) || !hasAnyTarget) return null
-      return transformFile(code, id, processor)
+      // Pass telemetry into the same traversal — avoids a second parse of the file.
+      return transformFile(code, id, processor, {telemetry: code.includes('Wu') ? telemetry : null})
     },
 
     /**
@@ -102,10 +123,20 @@ export default function wickuiI18nPlugin(options = {}) {
         res.setHeader('Content-Type', 'application/json')
         res.end(JSON.stringify(Object.fromEntries(processor.dictionary), null, 2))
       })
+      server.middlewares.use(`${base}telemetry.json`, (_req, res) => {
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify(telemetry.toJSON()))
+      })
     },
 
     /** Emit the translation dictionary as a build asset and print debug table. */
     generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: 'telemetry.json',
+        source: JSON.stringify(telemetry.toJSON()),
+      })
+
       this.emitFile({
         type: 'asset',
         fileName: 'wick-ui-i18n.json',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npm-questionpro/wick-ui-i18n",
-  "version": "2.0.0-next.29",
+  "version": "2.0.0-next.31",
   "private": false,
   "license": "ISC",
   "description": "Auto-translation AST wrapper for Wick UI",

package/src/extractStrings.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview extractStrings — collects every non-empty StringLiteral value
+ * from object properties and TypeScript enum members in a source file.
+ *
+ * Used for constant/enum files declared via the `dictionaryFiles` plugin option.
+ * No code is rewritten; keys are simply added to the translation dictionary.
+ *
+ * Handles:
+ *   export const LABEL = { BRAND_NAME: 'QuestionPro', ... }
+ *   enum Status { Active = 'Active', Draft = 'Draft' }
+ *   const enum Direction { Up = 'up', Down = 'down' }
+ *
+ * Skips:
+ *   empty strings, numeric enum members, computed keys, HTML entities
+ */
+
+import {parse} from '@babel/parser'
+import {traverse, BABEL_PLUGINS, HTML_ENTITY_RE, normalise} from './utils.js'
+
+/**
+ * Parse `code` and record every non-empty string literal value into the
+ * processor dictionary. Works for plain objects and TS enum declarations.
+ *
+ * @param {string} code
+ * @param {string} id   - File path (for collision warnings).
+ * @param {import('./processor.js').TranslationProcessor} processor
+ */
+export function extractStringsFromFile(code, id, processor) {
+  let ast
+  try {
+    ast = parse(code, {sourceType: 'module', plugins: BABEL_PLUGINS})
+  } catch {
+    processor.log(`[dictionaryFiles] failed to parse ${id} — skipping`)
+    return
+  }
+
+  traverse(ast, {
+    /** Object property with a string value: { BRAND_NAME: 'QuestionPro' } */
+    ObjectProperty(path) {
+      const value = path.node.value
+      if (value.type !== 'StringLiteral') return
+      const text = normalise(value.value)
+      if (!text) return
+      if (HTML_ENTITY_RE.test(text)) return
+      processor.record(text, text, id, '(dictionaryFiles:object)')
+    },
+
+    /** TypeScript enum member with a string initialiser: Active = 'Active' */
+    TSEnumMember(path) {
+      const init = path.node.initializer
+      if (!init || init.type !== 'StringLiteral') return
+      const text = normalise(init.value)
+      if (!text) return
+      if (HTML_ENTITY_RE.test(text)) return
+      processor.record(text, text, id, '(dictionaryFiles:enum)')
+    },
+  })
+}

package/src/processor.js

@@ -13,7 +13,7 @@ const DEFAULT_IGNORE = [
   'WuHelpButton',
   'WuActivityLog',
   'WuAppHeader',
-  'WuAPpHeadeMenu',
+  'WuAppHeaderMenu',
   'WuCopyToClipboard',
   'WuMenuIcon',
   'WuScrollArea',
@@ -27,17 +27,18 @@ export class TranslationProcessor {
    * @param {object}   options
    * @param {string[]} options.components          - Component names that trigger translation.
    * @param {string[]} [options.ignoreComponents]  - Extra components to exclude.
-   * @param {string[]} [options.translatableProps] - JSX prop names to rewrite to wt(). Overrides defaults.
-   * @param {string[]} [options.extractFromKeys]   - Object property names whose string values are recorded.
+   * @param {string[]} [options.translatableProps] - Extra JSX prop names to rewrite to useWt()(). Appended to defaults.
+   * @param {string[]} [options.dataLabelKeys]     - Object property names whose string values are labels in mixed
+   *                                                 data files (e.g. ['label', 'title'] in nav config arrays).
    * @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 {Set<string>} JSX prop names that should be translated. */
-    this.translatableProps = new Set(options.translatableProps ?? DEFAULT_TRANSLATABLE_PROPS)
+    this.translatableProps = new Set([...DEFAULT_TRANSLATABLE_PROPS, ...(options.translatableProps || [])])
     /** @type {Set<string>} Object property key names whose string values are extracted (e.g. 'label'). */
-    this.extractFromKeys = new Set(options.extractFromKeys || [])
+    this.extractFromKeys = new Set(options.dataLabelKeys || options.extractFromKeys || [])
     /** @type {Map<string, string>} key → original text */
     this.dictionary = new Map()
     /** @type {import('./debug.js').DebugEntry[]} */
@@ -76,7 +77,7 @@ export class TranslationProcessor {
    * component that should be translated.
    *
    * Rules (first match wins, walking outward):
-   *  - `data-skip` / `data-i18n-skip` attr  → ignored
+   *  - `data-i18n-skip` attr  → ignored
    *  - component in `ignoreComponents`       → ignored
    *  - `data-i18n-wrapper` attr OR component starts with "Wu" / is in `components` → translate
    *
@@ -93,7 +94,7 @@ export class TranslationProcessor {
       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))) {
+      if (attrs.some(a => a.name?.name === 'data-i18n-skip')) {
         isIgnored = true
         return true
       }
@@ -120,7 +121,8 @@ export class TranslationProcessor {
   /**
    * Return `true` when `propName` is in the translatable-props set and the
    * immediate parent JSX element is a Wu* component or in `components`, and
-   * is not in `ignoreComponents`. Matched props are rewritten to `{wt("...")}`. *
+   * is not in `ignoreComponents`. Matched props are rewritten to `{useWt()("...")}` by the transform.
+   *
    * @param {string} propName
    * @param {import('@babel/traverse').NodePath} path - JSXAttribute path.
    * @returns {boolean}
@@ -132,9 +134,9 @@ export class TranslationProcessor {
     const name = openingEl.name?.name || openingEl.name?.property?.name
     if (!name) return false
     if (this.ignoreComponents.has(name)) return false
-    // Respect data-skip / data-i18n-skip on the same element
+    // Respect data-i18n-skip on the same element
     const attrs = openingEl.attributes || []
-    if (attrs.some(a => ['data-skip', 'data-i18n-skip'].includes(a.name?.name))) return false
+    if (attrs.some(a => a.name?.name === 'data-i18n-skip')) return false
     return name.startsWith('Wu') || this.components.has(name)
   }
 

package/src/recordWtCalls.js

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview recordWtCalls — handles wt() and useWt()() call expressions:
+ *
+ *  1. recordWtCall   — records static string args into the translation dictionary.
+ *                      No code rewrite; wt/useWt handle runtime lookup.
+ *
+ *  2. transformWtTemplateLiteral — rewrites template literals with expressions
+ *                      so each static quasi becomes its own wt/useWt call:
+ *
+ *                        wt(`Hello ${name}`)
+ *                        → `${wt("Hello")} ${name}`
+ *
+ *                        useWt()(`Hello ${name}`)
+ *                        → `${useWt()("Hello")} ${name}`
+ *
+ * Both functions handle the same two call shapes:
+ *   wt(...)       — bare identifier callee
+ *   useWt()(...)  — call expression callee (useWt() returns the translate fn)
+ *
+ * Supported static arg forms:
+ *   wt("hello")        — StringLiteral → recorded, not rewritten
+ *   wt(`hello`)        — TemplateLiteral, no expressions → recorded, not rewritten
+ *   wt(`hello ${n}`)   — TemplateLiteral with expressions → each quasi recorded + rewritten
+ *
+ * Ignored:
+ *   wt(variable)       — dynamic, cannot be statically analysed
+ *   wt()  /  wt(a, b)  — wrong arity
+ */
+
+import {splitQuasi, normalise} from './utils.js'
+
+// ─── shared helper ────────────────────────────────────────────────────────────
+
+/**
+ * Detect whether `node` is a `wt(...)` or `useWt()(...)` call and return
+ * the wrapper string used to reconstruct translated quasis in the output.
+ *
+ * Returns `null` when the node is neither shape.
+ *
+ * @param {import('@babel/types').CallExpression} node
+ * @returns {{ wrapper: (text: string) => string, args: import('@babel/types').Node[] } | null}
+ */
+function getWtInfo(node) {
+  const {callee, arguments: args} = node
+
+  // wt(...)
+  if (callee.type === 'Identifier' && callee.name === 'wt') {
+    return {wrapper: text => `wt(${JSON.stringify(text)})`, args}
+  }
+
+  // useWt()(...)
+  if (
+    callee.type === 'CallExpression' &&
+    callee.callee.type === 'Identifier' &&
+    callee.callee.name === 'useWt' &&
+    callee.arguments.length === 0
+  ) {
+    return {wrapper: text => `useWt()(${JSON.stringify(text)})`, args}
+  }
+
+  return null
+}
+
+// ─── recordWtCall ─────────────────────────────────────────────────────────────
+
+/**
+ * If `path` is a `wt(staticString)` or `useWt()(staticString)` call, record
+ * the key in the processor dictionary. Returns `true` when a key was recorded.
+ *
+ * No code transformation is performed — wt/useWt handle runtime lookup.
+ *
+ * @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 info = getWtInfo(path.node)
+  if (!info) return false
+
+  const {args} = info
+  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 = normalise(text)
+  if (!cleanText) return false
+
+  processor.record(cleanText, cleanText, id, '(wt)')
+  return true
+}
+
+// ─── transformWtTemplateLiteral ───────────────────────────────────────────────
+
+/**
+ * Transform a `wt(...)` or `useWt()(...)` call whose argument is a TemplateLiteral
+ * with one or more dynamic expressions.
+ *
+ * Each static quasi is independently extracted and replaced with a nested
+ * `wt("text")` / `useWt()("text")` call; dynamic expressions are preserved in
+ * place. The whole call is replaced with a plain template literal:
+ *
+ *   wt(`Hello ${name}`)            →  `${wt("Hello")} ${name}`
+ *   wt(`${a} and ${b}`)            →  `${a} ${wt("and")} ${b}`
+ *   useWt()(`Hello ${name}`)       →  `${useWt()("Hello")} ${name}`
+ *   useWt()(`${a} and ${b}`)       →  `${a} ${useWt()("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 info = getWtInfo(path.node)
+  if (!info) return false
+
+  const {wrapper, args} = info
+  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}\${${wrapper(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
+}

package/src/telemetry.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Telemetry collector — scans consumer node_modules for
+ * @npm-questionpro/wick-ui-* versions and counts Wu* JSX component usages
+ * across the entire build. Emitted as `telemetry.json` at build time and
+ * served at `GET /telemetry.json` in dev.
+ *
+ * Intentionally isolated from i18n logic — no imports from other src/ files
+ * except shared utilities (no domain objects).
+ *
+ * Wu* component recording is done inside transformFile's existing traversal
+ * (via the `telemetry` option) so no second parse is needed per file.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export class TelemetryCollector {
+  constructor() {
+    /** @type {Record<string, string>} short name → version e.g. { lib: '2.0.0-next.29' } */
+    this.versions = {}
+    /** @type {Map<string, number>} PascalCase component name → total usage count */
+    this.counts = new Map()
+  }
+
+  /** Clear component counts — called on every buildStart so watch-mode rebuilds are clean. */
+  reset() {
+    this.counts.clear()
+  }
+
+  /**
+   * Increment the usage count for a Wu* component and record its prop names.
+   * @param {string}   name  - e.g. 'WuButton'
+   * @param {string[]} props - Prop names present on this usage e.g. ['variant', 'disabled']
+   */
+  record(name, props = []) {
+    if (!this.counts.has(name)) this.counts.set(name, {count: 0, props: new Map()})
+    const entry = this.counts.get(name)
+    entry.count++
+    for (const prop of props) {
+      entry.props.set(prop, (entry.props.get(prop) ?? 0) + 1)
+    }
+  }
+
+  /**
+   * Scan the consumer's node_modules for all @npm-questionpro/wick-ui-* packages
+   * and record their versions. Called once in configResolved when root is known.
+   *
+   * @param {string} root - Vite project root
+   */
+  scanVersions(root) {
+    const scopeDir = path.join(root, 'node_modules', '@npm-questionpro')
+    let entries
+    try {
+      entries = fs.readdirSync(scopeDir)
+    } catch {
+      // @npm-questionpro scope not present — skip silently
+      return
+    }
+    for (const name of entries) {
+      if (!name.startsWith('wick-ui-')) continue
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(scopeDir, name, 'package.json'), 'utf8'))
+        const shortKey = name.replace('wick-ui-', '')
+        this.versions[shortKey] = pkg.version
+      } catch {
+        // malformed or missing package.json — skip
+      }
+    }
+
+    // Also capture react and react-dom versions from the consumer's node_modules
+    for (const dep of ['react', 'react-dom']) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'node_modules', dep, 'package.json'), 'utf8'))
+        this.versions[dep] = pkg.version
+      } catch {
+        // not installed — skip
+      }
+    }
+  }
+
+  /**
+   * Produce the final telemetry payload as two clearly separated sections:
+   *  - `versions`: package version map (sorted alphabetically)
+   *  - `components`: Wu* usage counts with per-prop tallies (sorted alphabetically)
+   *
+   * Keeping the two sections distinct prevents a component named "react" or
+   * "lib" from silently shadowing a version entry.
+   *
+   * @returns {{ versions: Record<string, string>, components: Record<string, object> }}
+   */
+  toJSON() {
+    const versions = Object.fromEntries(Object.entries(this.versions).sort(([a], [b]) => a.localeCompare(b)))
+    const components = Object.fromEntries(
+      [...this.counts.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, {count, props}]) => [
+          name,
+          {
+            count,
+            props: Object.fromEntries([...props.entries()].sort(([a], [b]) => a.localeCompare(b))),
+          },
+        ]),
+    )
+    return {versions, components}
+  }
+}

package/src/transform.js

@@ -1,30 +1,18 @@
 /**
  * @fileoverview AST transform — parses a JSX/TSX/TS file and:
  *   - Rewrites JSX text content inside Wu* components to `<WuTranslate>`
- *   - Rewrites translatable props (placeholder, title, …) to `{wt("…")}`
+ *   - Rewrites translatable props (placeholder, title, …) to `{useWt()("…")}`
  *   - Prepends the necessary imports when added.
+ *   - Optionally records Wu* component usages into a TelemetryCollector.
  */
 
 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 './transformReactTextWithEntities.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]+);/
+import {recordWtCall, transformWtTemplateLiteral} from './recordWtCalls.js'
+import {traverse, BABEL_PLUGINS, HTML_ENTITY_RE, normalise, splitQuasi} from './utils.js'
 
 /** @param {import('@babel/types').Node} node @returns {string|null} */
 function getStaticString(node) {
@@ -73,10 +61,7 @@ function handleConditional(expr, path, ms, processor, id) {
  * @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, ' ')
+  const cleanText = normalise(text)
   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.
@@ -89,6 +74,66 @@ function handleCapture(path, text, start, end, ms, processor, id, skipExplicitKe
   return true
 }
 
+/**
+ * Transform a JSX prop value that is a TemplateLiteral into a useWt()() call
+ * (or a new template literal with useWt()() for each static quasi).
+ *
+ * Static:  Label={`hello`}              → Label={useWt()("hello")}
+ * Dynamic: Label={`${name} hello`}       → Label={`${name} ${useWt()("hello")}`}
+ * Dynamic: Label={`${a} and ${b}`}       → Label={`${a} ${useWt()("and")} ${b}`}
+ *
+ * @param {import('@babel/traverse').NodePath} path - JSXAttribute path.
+ * @param {import('@babel/types').TemplateLiteral} expr
+ * @param {string} code
+ * @param {import('magic-string').default} ms
+ * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {string} id
+ * @returns {boolean} `true` when a replacement was written.
+ */
+function transformPropTemplateLiteral(path, expr, code, ms, processor, id) {
+  if (!processor.shouldTranslateProp(path.node.name.name, path)) return false
+
+  const {quasis, expressions} = expr
+  const componentTree = getComponentTree(path)
+
+  // Static template literal: no expressions
+  if (expressions.length === 0) {
+    const text = normalise(quasis[0].value.cooked ?? quasis[0].value.raw)
+    if (!text || HTML_ENTITY_RE.test(text)) return false
+    processor.record(text, text, id, componentTree)
+    // Overwrite the entire JSXExpressionContainer
+    ms.overwrite(path.node.value.start, path.node.value.end, `{useWt()(${JSON.stringify(text)})}`)
+    return true
+  }
+
+  // Dynamic template literal: walk quasis, replace static parts with useWt()()
+  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 && !HTML_ENTITY_RE.test(text)) {
+      processor.record(text, text, id, componentTree)
+      parts.push(`${leading}\${useWt()(${JSON.stringify(text)})}${trailing}`)
+      hasTranslatable = true
+    } else {
+      parts.push(cooked)
+    }
+
+    if (i < expressions.length) {
+      parts.push(`\${${code.slice(expressions[i].start, expressions[i].end)}}`)
+    }
+  }
+
+  parts.push('`')
+  if (!hasTranslatable) return false
+
+  ms.overwrite(path.node.value.start, path.node.value.end, `{${parts.join('')}}`)
+  return true
+}
+
 /**
  * Parse `code`, replace all translatable JSX text nodes, and prepend the
  * `WuTranslate` import when necessary.
@@ -96,10 +141,14 @@ function handleCapture(path, text, start, end, ms, processor, id, skipExplicitKe
  * @param {string} code - Raw source of the file.
  * @param {string} id   - File path.
  * @param {import('./processor.js').TranslationProcessor} processor
+ * @param {object} [options]
+ * @param {import('./telemetry.js').TelemetryCollector|null} [options.telemetry]
+ *   When provided, Wu* JSX component usages are recorded into this collector
+ *   inside the same traversal — avoiding a second parse of the file.
  * @returns {{ code: string, map: object } | null} Transformed result, or
  *   `null` when no changes were made.
  */
-export function transformFile(code, id, processor) {
+export function transformFile(code, id, processor, {telemetry} = {}) {
   const ast = parse(code, {
     sourceType: 'module',
     plugins: BABEL_PLUGINS,
@@ -108,19 +157,18 @@ export function transformFile(code, id, processor) {
   const ms = new MagicString(code)
   let needsImport = false
   let hasImport = false
-  let hasWtTransform = false
-  let needsWtImport = false
-  let hasWtImport = false
+  let needsUseWtImport = false
+  let hasUseWtImport = false
 
   traverse(ast, {
-    /** wt("static string") call — record the key in the dictionary.
-     * No code transformation; wt() handles runtime lookup.
+    /**
+     * wt("static string") / useWt()("static string") — record the key.
+     * wt(`quasi ${expr}`) / useWt()(`quasi ${expr}`) — rewrite each static
+     * quasi to its own wt/useWt call and record it.
      */
     CallExpression(path) {
       if (recordWtCall(path, processor, id)) return
-      if (transformWtTemplateLiteral(path, code, ms, processor, id)) {
-        hasWtTransform = true
-      }
+      transformWtTemplateLiteral(path, code, ms, processor, id)
     },
 
     /** Track whether WuTranslate / wt are already imported so we don't duplicate them. */
@@ -128,7 +176,7 @@ export function transformFile(code, id, processor) {
       if (path.node.source.value.includes('wick-ui-lib')) {
         for (const s of path.node.specifiers) {
           if (s.imported?.name === 'WuTranslate') hasImport = true
-          if (s.imported?.name === 'wt') hasWtImport = true
+          if (s.imported?.name === 'useWt') hasUseWtImport = true
         }
       }
     },
@@ -136,7 +184,7 @@ export function transformFile(code, id, processor) {
     /**
      * Data-file key extraction: records string values of configured object
      * property names (e.g. `label: 'Analytics'`) without rewriting code.
-     * Enabled via `extractFromKeys` option.
+     * Enabled via the `dataLabelKeys` plugin option.
      */
     ObjectProperty(path) {
       if (!processor.extractFromKeys.size) return
@@ -145,10 +193,7 @@ export function transformFile(code, id, processor) {
       if (!keyName || !processor.extractFromKeys.has(keyName)) return
       const value = path.node.value
       if (value.type !== 'StringLiteral') return
-      const text = value.value
-        .trim()
-        .replace(/\n/g, ' ')
-        .replace(/\s{2,}/g, ' ')
+      const text = normalise(value.value)
       if (!text) return
       if (HTML_ENTITY_RE.test(text)) return
       processor.record(text, text, id, '(data)')
@@ -156,28 +201,39 @@ export function transformFile(code, id, processor) {
 
     /**
      * Translatable props (Label, placeholder, title, aria-label, ...)
-     * rewritten to `{wt("foo")}` on Wu* components.
+     * rewritten to `{useWt()("foo")}` on Wu* components.
+     *
+     * Handles all three value shapes:
+     *   Label="hello"              → Label={useWt()("hello")}
+     *   Label={`hello`}            → Label={useWt()("hello")}
+     *   Label={`${name} hello`}    → Label={`${name} ${useWt()("hello")}`}
      */
     JSXAttribute(path) {
       const propName = path.node.name.name
       if (typeof propName !== 'string') return
       const value = path.node.value
-      if (!value || value.type !== 'StringLiteral') return
-
-      const rawValue = code.slice(value.start, value.end)
-      if (HTML_ENTITY_RE.test(rawValue)) return
+      if (!value) return
 
-      const text = value.value
-        .trim()
-        .replace(/\n/g, ' ')
-        .replace(/\s{2,}/g, ' ')
-      if (!text) return
-
-      if (!processor.shouldTranslateProp(propName, path)) return
+      // Shape 1: StringLiteral  —  Label="hello"
+      if (value.type === 'StringLiteral') {
+        const rawValue = code.slice(value.start, value.end)
+        if (HTML_ENTITY_RE.test(rawValue)) return
+        const text = normalise(value.value)
+        if (!text) return
+        if (!processor.shouldTranslateProp(propName, path)) return
+        processor.record(text, text, id, getComponentTree(path))
+        ms.overwrite(value.start, value.end, `{useWt()(${JSON.stringify(text)})}`)
+        needsUseWtImport = true
+        return
+      }
 
-      processor.record(text, text, id, getComponentTree(path))
-      ms.overwrite(value.start, value.end, `{wt(${JSON.stringify(text)})}`)
-      needsWtImport = true
+      // Shape 2 & 3: JSXExpressionContainer wrapping a TemplateLiteral
+      //   Label={`hello`}  or  Label={`${name} hello`}
+      if (value.type === 'JSXExpressionContainer' && value.expression.type === 'TemplateLiteral') {
+        if (transformPropTemplateLiteral(path, value.expression, code, ms, processor, id)) {
+          needsUseWtImport = true
+        }
+      }
     },
 
     /** Plain JSX text: `<Foo>Hello world</Foo>` */
@@ -231,12 +287,26 @@ export function transformFile(code, id, processor) {
         needsImport = true
       }
     },
+
+    /**
+     * Telemetry: record Wu* component usages when a collector is provided.
+     * Runs in the same traversal to avoid parsing the file a second time.
+     */
+    JSXOpeningElement(path) {
+      if (!telemetry) return
+      const name = path.node.name.name
+      if (typeof name !== 'string' || !name.startsWith('Wu')) return
+      const props = path.node.attributes
+        .filter(a => a.type === 'JSXAttribute' && typeof a.name?.name === 'string')
+        .map(a => a.name.name)
+      telemetry.record(name, props)
+    },
   })
 
-  if (!needsImport && !hasWtTransform && !needsWtImport) return null
+  if (!ms.hasChanged()) return null
 
-  if (needsWtImport && !hasWtImport) {
-    ms.prepend(`import { wt } from '@npm-questionpro/wick-ui-lib';\n`)
+  if (needsUseWtImport && !hasUseWtImport) {
+    ms.prepend(`import { useWt } from '@npm-questionpro/wick-ui-lib';\n`)
   }
 
   if (needsImport && !hasImport) {

package/src/transformReactTextWithEntities.js

@@ -18,6 +18,7 @@
  */
 
 import {getComponentTree} from './debug.js'
+import {splitQuasi} from './utils.js'
 
 /**
  * Splits the raw source around HTML entities (capturing group keeps entities
@@ -33,25 +34,6 @@ const HTML_ENTITY_SPLIT_RE = /(&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);
  */
 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.
  *
@@ -97,7 +79,8 @@ export function transformJsxTextWithEntities(path, rawSource, ms, processor, id)
       // Raw entity — emit as-is, no translation key
       parts.push(seg)
     } else {
-      const {leading, text, trailing} = splitSegment(seg)
+      // splitQuasi normalises internal whitespace and separates leading/trailing padding
+      const {leading, text, trailing} = splitQuasi(seg)
 
       if (text) {
         processor.record(text, text, id, componentTree)

package/src/transformTemplateLiteral.js

@@ -11,21 +11,7 @@
  */
 
 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}
-}
+import {splitQuasi, HTML_ENTITY_RE} from './utils.js'
 
 /**
  * Transform a JSXExpressionContainer whose expression is a TemplateLiteral
@@ -35,6 +21,7 @@ function splitQuasi(raw) {
  *   → <><WuTranslate __i18nKey="hello" /> {name} <WuTranslate __i18nKey="how are you" /></>
  *
  * Quasis that are empty or whitespace-only are skipped (no key emitted).
+ * Quasis that contain HTML entities are emitted as plain text (not wrapped).
  * Leading/trailing whitespace within a quasi is preserved as JSX text around
  * the WuTranslate element so words don't run together after translation.
  *
@@ -61,9 +48,14 @@ export function transformTemplateLiteralExpression(path, code, ms, processor, id
     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
+      if (HTML_ENTITY_RE.test(text)) {
+        // Entity-like string in this quasi — preserve as literal JSX text, no key
+        parts.push(cooked)
+      } else {
+        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)
 

package/src/utils.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Shared utilities used across all transform modules:
+ * Babel traversal setup, constants, and text-normalisation helpers.
+ *
+ * Having a single source of truth here ensures every module applies
+ * identical normalisation and uses the same regex/plugin list.
+ */
+
+import _traverse from '@babel/traverse'
+
+/** @babel/traverse ESM/CJS interop — handles both `import traverse` forms. */
+export const traverse = _traverse.default || _traverse
+
+/** Babel parser plugins applied to every file. */
+export const BABEL_PLUGINS = ['jsx', 'typescript']
+
+/**
+ * Matches any HTML entity: named (&), decimal (©), or hex (©).
+ * 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 & → "&",   → "\u00a0", etc.).
+ */
+export const HTML_ENTITY_RE = /&(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);/
+
+/**
+ * Normalise a raw string: trim edges, then collapse newlines and whitespace
+ * runs to a single space. Applied to every string before it is used as a
+ * translation key so keys are stable regardless of source formatting.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalise(raw) {
+  return raw
+    .trim()
+    .replace(/\n/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+}
+
+/**
+ * Split a template quasi (or any padded string segment) into leading
+ * whitespace, normalised translatable text, and trailing whitespace.
+ *
+ * Leading/trailing whitespace is preserved separately so spacing around
+ * the replacement node is maintained in the reconstructed JSX output.
+ * The middle part is passed through `normalise` so keys are consistent.
+ *
+ * Used by both the JSX template-literal transformer and the wt() template
+ * transformer — a single shared implementation ensures the two paths
+ * produce identical keys for the same source text.
+ *
+ * @param {string} raw - Cooked value of a TemplateElement or a split text segment.
+ * @returns {{ leading: string, text: string, trailing: string }}
+ */
+export function splitQuasi(raw) {
+  const leading = raw.match(/^\s*/)[0]
+  const trailing = raw.match(/\s*$/)[0]
+  const text = normalise(raw.slice(leading.length, raw.length - trailing.length))
+  return {leading, text, trailing}
+}

package/src/transformWtCalls.js

@@ -1,135 +0,0 @@
-/**
- * @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
-}