@npm-questionpro/wick-ui-i18n 2.0.0-next.9 → 2.1.0-rc.0

package/README.md

@@ -1,105 +1,50 @@
 # 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
+---
 
-Defaults: `Label`, `placeholder`, `title`, `aria-label`, `aria-placeholder`.
+## Quick start
 
-| 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" />`      | ❌                                  |
+```ts
+// vite.config.ts
+import wickI18n from '@npm-questionpro/wick-ui-i18n'
+export default defineConfig({plugins: [react(), wickI18n()]})
+```
 
-## `wt()` calls
+---
 
-Plugin records static args into `wick-ui-i18n.json`. No code rewrite unless
-template literal with expressions.
+## What it transforms
 
-| 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}`)``            | ❌                    | —                                             |
+| 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}` ``           |
 
-## Data files (`extractFromKeys` option)
+---
 
-No code rewrite — keys only recorded in `wick-ui-i18n.json`.
+## Options
 
-| Input                                                   | Dictionary       |
-| ------------------------------------------------------- | ---------------- |
-| `{ label: 'Analytics' }` + `extractFromKeys: ['label']` | ✅ `"Analytics"` |
-| `{ label: variable }`                                   | ❌               |
-| `{ label: '' }`                                         | ❌               |
+| 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`   | —                                                                 | Globs (project files via Vite) or exact paths (anywhere, incl. `node_modules` via `fs`) |
+| `excludeFiles`      | —                                                                 | Files skipped entirely                                                                  |
+| `debug`             | `false`                                                           | Print extraction table at build                                                         |
 
 ---
 
-## 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,26 +5,61 @@ 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.
+   *
+   * Two modes depending on the value:
+   * - **Glob patterns** (`'src/enums/*.ts'`) — matched via Vite's transform pipeline.
+   *   Works for files in your project; does **not** reach `node_modules`.
+   * - **Exact paths** (`'node_modules/@company/shared/enums.ts'`) — read directly
+   *   with `fs` at build time, bypassing Vite's transform pipeline. Use this for
+   *   `node_modules` files. Missing files produce a `console.warn`.
+   *
+   * Both modes can be mixed in the same array.
+   *
+   * @example
+   * dictionaryFiles: [
+   *   'src/enums/*.ts',                              // glob — project files
+   *   'node_modules/@company/shared/enums.ts',       // exact — node_modules
+   * ]
+   */
+  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
 }
 
@@ -32,7 +67,9 @@ export interface WickI18nOptions {
  * 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

@@ -18,18 +18,27 @@
  * };
  */
 
+import fs from 'node:fs'
+import path from 'node:path'
 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|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} [excludeFiles]   - Files to skip (passed as `exclude` to Vite's createFilter).
  * @property {boolean}   [debug]             - Log transform activity to the console.
  */
 
@@ -40,17 +49,30 @@ 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,
     debug: options.debug,
   })
 
   const filter = createFilter([/\.(jsx|tsx|ts)$/], options.excludeFiles)
+  const enumFilter = options.dictionaryFiles ? createFilter(options.dictionaryFiles) : null
+
+  // Exact-path entries from dictionaryFiles (no glob chars) are read via fs in buildStart
+  // so they work for node_modules files that Vite never processes through transforms.
+  const dictionaryPatterns = (() => {
+    const raw = options.dictionaryFiles
+    if (!raw) return []
+    const arr = Array.isArray(raw) ? raw : [raw]
+    return arr.filter(p => typeof p === 'string' && !/[*?{}[\]]/.test(p))
+  })()
 
   let base = '/'
+  let root = '/'
 
   return {
     name: 'wick-ui-i18n',
@@ -64,6 +86,8 @@ export default function wickuiI18nPlugin(options = {}) {
      */
     configResolved(resolvedConfig) {
       base = resolvedConfig.base
+      root = resolvedConfig.root
+      telemetry.scanVersions(resolvedConfig.root)
     },
 
     /**
@@ -73,6 +97,17 @@ export default function wickuiI18nPlugin(options = {}) {
     buildStart() {
       processor.dictionary.clear()
       processor.entries = []
+      telemetry.reset()
+
+      for (const rel of dictionaryPatterns) {
+        const abs = path.isAbsolute(rel) ? rel : path.resolve(root, rel)
+        try {
+          const code = fs.readFileSync(abs, 'utf8')
+          extractStringsFromFile(code, abs, processor)
+        } catch {
+          console.warn(`[wick-i18n] dictionaryFiles: could not read "${rel}" — file not found or unreadable`)
+        }
+      }
     },
 
     /**
@@ -83,15 +118,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) ||
-        (processor.components.size > 0 &&
-          [...processor.components].some(c => code.includes(c))) ||
-        (processor.extractFromKeys.size > 0 &&
-          [...processor.extractFromKeys].some(k => code.includes(k)))
+        /\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,22 +138,26 @@ export default function wickuiI18nPlugin(options = {}) {
     configureServer(server) {
       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),
-        )
+        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',
-        source: JSON.stringify(
-          Object.fromEntries(processor.dictionary),
-          null,
-          2,
-        ),
+        source: JSON.stringify(Object.fromEntries(processor.dictionary), null, 2),
       })
 
       printReport(processor.entries)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npm-questionpro/wick-ui-i18n",
-  "version": "2.0.0-next.9",
+  "version": "2.1.0-rc.0",
   "private": false,
   "license": "ISC",
   "description": "Auto-translation AST wrapper for Wick UI",
@@ -34,13 +34,10 @@
     "index.d.ts",
     "src"
   ],
-  "prettier": "@npm-questionpro/wick-ui-prettier-config",
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ci": "vitest run --coverage",
-    "format": "prettier --write .",
-    "format:ci": "prettier --check .",
     "lint": "eslint . --fix",
     "lint:ci": "eslint --max-warnings 0 ."
   }

package/src/debug.js

@@ -16,9 +16,7 @@ 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
+      const name = p.node.openingElement.name.name || p.node.openingElement.name.property?.name
       if (name) parts.unshift(name)
     }
     return false
@@ -50,19 +48,15 @@ export function printReport(entries) {
 
   const rows = entries.map(e => [e.text, basename(e.file), e.componentTree])
 
-  const widths = headers.map((h, i) =>
-    Math.max(h.length, ...rows.map(r => r[i].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 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 row = cells => '│' + cells.map((c, i) => ` ${pad(c, widths[i])} `).join('│') + '│'
 
   const lines = [
     '',

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

@@ -4,13 +4,7 @@
  */
 
 /** Prop names translated by default on Wu* components. Pass `translatableProps` to override. */
-const DEFAULT_TRANSLATABLE_PROPS = [
-  'Label',
-  'placeholder',
-  'title',
-  'aria-label',
-  'aria-placeholder',
-]
+const DEFAULT_TRANSLATABLE_PROPS = ['Label', 'placeholder', 'title', 'aria-label', 'aria-placeholder']
 
 /** Components always excluded from translation regardless of user config. */
 const DEFAULT_IGNORE = [
@@ -19,7 +13,7 @@ const DEFAULT_IGNORE = [
   'WuHelpButton',
   'WuActivityLog',
   'WuAppHeader',
-  'WuAPpHeadeMenu',
+  'WuAppHeaderMenu',
   'WuCopyToClipboard',
   'WuMenuIcon',
   'WuScrollArea',
@@ -33,21 +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 || []),
-    )
+    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 || [])
     /** @type {Map<string, string>} key → original text */
     this.dictionary = new Map()
     /** @type {import('./debug.js').DebugEntry[]} */
@@ -74,9 +65,7 @@ export class TranslationProcessor {
    */
   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}"`,
-      )
+      console.warn(`[wick-i18n] Collision in ${file}\nKey: "${key}"\nNew: "${text}"`)
       return
     }
     this.dictionary.set(key, text)
@@ -88,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
    *
@@ -102,14 +91,10 @@ export class TranslationProcessor {
     path.findParent(p => {
       if (!p.isJSXElement()) return false
 
-      const name =
-        p.node.openingElement.name.name ||
-        p.node.openingElement.name.property?.name
+      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
       }
@@ -136,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}
@@ -148,10 +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)
   }
 
@@ -166,14 +151,9 @@ export class TranslationProcessor {
     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',
-      )
+      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
+      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.`,