gulp-mu-gulp-api 0.2.1 → 0.3.1

package/README.md

@@ -20,10 +20,19 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.0
+
+- **Added** integrated i18x console layer: `Log`, `Warn`, `LogError`, `Translate`, `GetLid`, `SetLid`, `GetTimeZone`, `DateInTimeZone`, `InstallStringExtensions` — translations live in the consumer project's `i18x/gulp/<lid>.json`; language follows `MICROGULP_LANG` (set by the µGulp dashboard) with locale fallback.
+- **Added** µLib-compatible `String.prototype.i18xTrans()` / `.i18xRegister()` (installed automatically on import).
+- **Removed** `µMeta()` / `MicroGulpMeta` — embed the context tag in the source phrase and use `.i18xRegister()` instead (see below).
+
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, µMeta } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+
+// Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
+InstallStringExtensions();
 
 export async function BUILD_THEME() {
     // single inputs
@@ -50,8 +59,8 @@ export async function BUILD_THEME() {
     PlaySignal('success');
     Speak('Theme build finished.');
 }
-BUILD_THEME.µDisplayName = µMeta('Build Theme', 'µDisplayName');
-BUILD_THEME.µDescription = µMeta('Compiles the Carbon/Neon dashboard skin.', 'µDescription');
+BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
+BUILD_THEME.µDescription = 'Compiles the Carbon/Neon dashboard skin.<context="µDescription"/>'.i18xRegister();
 ```
 
 Complete forms in one go:
@@ -75,7 +84,10 @@ let values = await RequestForm({
 | Function | Purpose |
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard (`IsUGulp` is a deprecated alias) |
-| `µMeta(text, property)` | Marks a µXXX task metadata string with an i18xe context tag (`µDisplayName`, `µDescription`, `µTooltip`, `µGroup`) |
+| `InstallStringExtensions()` | Installs µLib-compatible `String.prototype.i18xTrans()`/`i18xRegister()` (auto-run on import) |
+| `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) |
+| `Translate(text, values?)` | Returns the translated string without logging |
+| `GetLid()` / `SetLid(lid?)` | Active language id; `SetLid` clears to automatic when omitted |
 | `ReportProgress(value, label?)` | Report progress `0..1` to the task progress bar |
 | `CreateProgress(label?)` | Reporter object with `Update(value, stepLabel?)` and `Done()` |
 | `PlaySignal(signal?)` | Acoustic signal in the dashboard: `'success'` \| `'error'` \| `'attention'` (default) |
@@ -87,6 +99,29 @@ let values = await RequestForm({
 | `RequestSelectInput(options)` | Single selection from a fixed option list |
 | `RequestMultiSelectInput(options)` | Multi selection (checkbox group), always resolves to a `string[]` |
 
+### Localized task metadata (`.i18xRegister()` + placeholders)
+
+Write the i18xe context tag **into** the source phrase and mark it with `.i18xRegister()` — that marker is what the `i18xe-sync` tooling scans for, and at runtime it returns the phrase unchanged (the classic gulp CLI keeps seeing a plain string). Use i18xe placeholder tags in the source text. The dashboard substitutes a standard property set when translating:
+
+| Placeholder | Source |
+| :--- | :--- |
+| `version` | `µI18nContext.version` export, else `package.json` |
+| `project` | `µI18nContext.project` export, else `package.json` `name` |
+| `workspace` | workspace folder name |
+| `source` | gulpfile path relative to the workspace |
+| `gulpfile` | gulpfile file name |
+| `task` | technical export name |
+| `taskId` | composite id `source::task` |
+
+Export defaults from the gulpfile (overrides `package.json`):
+
+```javascript
+export const µI18nContext = { version: '1.13', project: 'eMP' };
+
+MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
+// => "Make Build V1.13" in the dashboard (translatable per language)
+```
+
 ### Field types (for `RequestForm`)
 
 A field descriptor is `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.
@@ -143,10 +178,19 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.0
+
+- **Neu** integrierte i18x-Konsolenschicht: `Log`, `Warn`, `LogError`, `Translate`, `GetLid`, `SetLid`, `GetTimeZone`, `DateInTimeZone`, `InstallStringExtensions` — Übersetzungen liegen im Verbraucherprojekt unter `i18x/gulp/<lid>.json`; die Sprache folgt `MICROGULP_LANG` (vom µGulp-Dashboard gesetzt) mit Locale-Fallback.
+- **Neu** µLib-kompatible `String.prototype.i18xTrans()` / `.i18xRegister()` (werden beim Import automatisch installiert).
+- **Entfernt** `µMeta()` / `MicroGulpMeta` — Kontext-Tag in die Textphrase schreiben und `.i18xRegister()` verwenden (siehe unten).
+
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, µMeta } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+
+// Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
+InstallStringExtensions();
 
 export async function BUILD_THEME() {
     // Einzeleingaben
@@ -173,8 +217,8 @@ export async function BUILD_THEME() {
     PlaySignal('success');
     Speak('Theme build finished.');
 }
-BUILD_THEME.µDisplayName = µMeta('Build Theme', 'µDisplayName');
-BUILD_THEME.µDescription = µMeta('Kompiliert den Carbon/Neon-Dashboard-Skin.', 'µDescription');
+BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
+BUILD_THEME.µDescription = 'Kompiliert den Carbon/Neon-Dashboard-Skin.<context="µDescription"/>'.i18xRegister();
 ```
 
 Komplette Formulare in einem Rutsch:
@@ -198,7 +242,10 @@ let values = await RequestForm({
 | Funktion | Zweck |
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft (`IsUGulp` ist ein veralteter Alias) |
-| `µMeta(text, property)` | Kennzeichnet einen µXXX-Metadaten-String mit einem i18xe-Kontext-Tag (`µDisplayName`, `µDescription`, `µTooltip`, `µGroup`) |
+| `InstallStringExtensions()` | Installiert µLib-kompatible `String.prototype.i18xTrans()`/`i18xRegister()` (läuft beim Import automatisch) |
+| `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x (`<context="task log"/>` usw.) |
+| `Translate(text, values?)` | Gibt den übersetzten String zurück, ohne zu loggen |
+| `GetLid()` / `SetLid(lid?)` | Aktive Sprach-ID; `SetLid` ohne Argument = automatische Auflösung |
 | `ReportProgress(value, label?)` | Fortschritt `0..1` an die Task-Progressbar melden |
 | `CreateProgress(label?)` | Reporter-Objekt mit `Update(value, stepLabel?)` und `Done()` |
 | `PlaySignal(signal?)` | Akustisches Signal im Dashboard: `'success'` \| `'error'` \| `'attention'` (Default) |
@@ -210,6 +257,29 @@ let values = await RequestForm({
 | `RequestSelectInput(options)` | Einzelauswahl aus fester Optionsliste |
 | `RequestMultiSelectInput(options)` | Mehrfachauswahl (Checkbox-Gruppe), löst immer mit `string[]` auf |
 
+### Lokalisierte Task-Metadaten (`.i18xRegister()` + Platzhalter)
+
+Den i18xe-Kontext-Tag **in** die Textphrase schreiben und mit `.i18xRegister()` markieren — genau diese Markierung scannt das `i18xe-sync`-Tooling, zur Laufzeit gibt sie den Text unverändert zurück (die klassische gulp-CLI sieht weiterhin einen einfachen String). i18xe-Platzhalter im Quelltext verwenden. Beim Übersetzen setzt das Dashboard einen Standardsatz ein:
+
+| Platzhalter | Quelle |
+| :--- | :--- |
+| `version` | `µI18nContext.version`-Export, sonst `package.json` |
+| `project` | `µI18nContext.project`-Export, sonst `package.json` `name` |
+| `workspace` | Workspace-Ordnername |
+| `source` | Gulpfile-Pfad relativ zum Workspace |
+| `gulpfile` | Gulpfile-Dateiname |
+| `task` | technischer Exportname |
+| `taskId` | zusammengesetzte Id `source::task` |
+
+Defaults im Gulpfile exportieren (`package.json` wird überschrieben):
+
+```javascript
+export const µI18nContext = { version: '1.13', project: 'eMP' };
+
+MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
+// => „Make Build V1.13“ im Dashboard (pro Sprache übersetzbar)
+```
+
 ### Feldtypen (für `RequestForm`)
 
 Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.2.1",
-	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
+	"version": "0.3.1",
+	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output, localized console output (i18x) and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
 	"type": "module",
 	"main": "src/index.mjs",
 	"exports": {
@@ -22,6 +22,9 @@
 		"interactive",
 		"sound",
 		"speech",
+		"i18n",
+		"i18x",
+		"localization",
 		"prompt",
 		"multiselect",
 		"form",

package/src/i18x.mjs

@@ -0,0 +1,306 @@
+// ===========================================
+// gulp-mu-gulp-api — i18x console output for gulp tasks
+// © 2026 Meinolf Amekudzi
+// (published under MIT license)
+// ===========================================
+
+/**
+ * Localized console output for gulp tasks, following the i18xe notation:
+ * source strings are American English and carry a context tag
+ * (`<context="task log"/>` …); translations live in the *consumer project's*
+ * own `i18x/gulp/<lid>.json` files and `<name/>` placeholders are filled at
+ * render time. Any project using µGulp drops an `i18x/gulp` directory next to
+ * its gulpfile and its build output is localized — no coupling to µGulp
+ * internals, works from the plain `gulp` CLI as well.
+ *
+ * The active language resolves from `MICROGULP_LANG` (the µGulp engine
+ * forwards the dashboard language here), then the host OS locale, then the
+ * en-US source. Regional/script variants fall back through a compact map
+ * (`de-AT` → `de-DE`, `zh-TW` → `zh-CN`, `en-GB` → `en-US`, …) onto whichever
+ * languages the project actually ships.
+ *
+ * @example
+ * import { Log, Warn } from 'gulp-mu-gulp-api';
+ * export async function BUILD() {
+ *     Log('Compiling styles\u2026<context="task log"/>');
+ *     Log('Chunk <n/>/<total/> written<context="task log"/>', { n: 3, total: 5 });
+ * }
+ *
+ * @module gulp-mu-gulp-api/i18x
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DEFAULT_LID = 'en-US';
+
+// Compact locale fallback tables (subset of the µLib i18x LIDS_MAPS /
+// LIDS_MAIN_CULTURES). The resolver also falls back on the bare language
+// prefix, so only the non-obvious chains need listing.
+const LIDS_MAPS = {
+	'zh-CHS': ['zh-CN'], 'zh-CHT': ['zh-CHS', 'zh-CN'], 'zh-HK': ['zh-CHS', 'zh-CN'],
+	'zh-Hans': ['zh-CHS', 'zh-CN'], 'zh-Hant': ['zh-CHT', 'zh-CHS', 'zh-CN'],
+	'zh-MO': ['zh-CHS', 'zh-CN'], 'zh-SG': ['zh-CHS', 'zh-CN'], 'zh-TW': ['zh-CHT', 'zh-CHS', 'zh-CN'],
+	'de-CH': ['de-DE'], 'de-AT': ['de-DE'], 'de-LU': ['de-DE'], 'de-LI': ['de-DE'],
+	'en-GB': ['en-US'], 'en-AU': ['en-GB', 'en-US'], 'en-CA': ['en-GB', 'en-US'],
+};
+const LIDS_MAIN_CULTURES = {
+	zh: 'CN', de: 'DE', en: 'GB', fr: 'FR', es: 'ES', it: 'IT', pt: 'PT',
+	nl: 'NL', ru: 'RU', ja: 'JP', ko: 'KR',
+};
+
+let dictionaryCache = new Map();
+let availableLids = null;
+let activeLid = null;
+const timeZoneFormatters = {};
+
+/** @returns {string} IANA timezone from MICROGULP_TZ, then ECMAScript Intl */
+export function GetTimeZone() {
+	if (process.env.MICROGULP_TZ) return process.env.MICROGULP_TZ;
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+	} catch {
+		return 'UTC';
+	}
+}
+
+/** Wall-clock Date in an IANA timezone (µLib-compatible). */
+export function DateInTimeZone(_date, _timeZone) {
+	let tz = _timeZone || GetTimeZone();
+	try {
+		let formatter = timeZoneFormatters[tz];
+		if (formatter === undefined) {
+			formatter = new Intl.DateTimeFormat('en-US', {
+				timeZone: tz, hour12: false,
+				year: 'numeric', month: '2-digit', day: '2-digit',
+				hour: '2-digit', minute: '2-digit', second: '2-digit',
+			});
+			timeZoneFormatters[tz] = formatter;
+		}
+		let values = {};
+		for (let part of formatter.formatToParts(_date)) values[part.type] = part.value;
+		return new Date(
+			parseInt(values.year, 10), parseInt(values.month, 10) - 1, parseInt(values.day, 10),
+			parseInt(values.hour, 10) % 24, parseInt(values.minute, 10), parseInt(values.second, 10),
+			_date.getMilliseconds(),
+		);
+	} catch {
+		return _date;
+	}
+}
+
+/** Normalizes casing: language lower, 2-letter region upper, 4-letter script Title. */
+function _NormalizeLid(_lid) {
+	if (!_lid) return '';
+	let parts = String(_lid).replace(/_/g, '-').trim().split('-').filter(Boolean);
+	if (parts.length === 0) return '';
+	return parts.map((_part, _index) => {
+		if (_index === 0) return _part.toLowerCase();
+		if (_part.length === 2) return _part.toUpperCase();
+		if (_part.length === 4) return _part.charAt(0).toUpperCase() + _part.slice(1).toLowerCase();
+		return _part;
+	}).join('-');
+}
+
+/**
+ * Picks the closest shipped language for a wanted locale: exact
+ * (case-insensitive) → LIDS_MAPS chain → main culture → language prefix →
+ * en-US default → first available.
+ */
+function _BestAvailableLid(_wantedLid, _available) {
+	if (_available.length === 0) return DEFAULT_LID;
+	let wanted = _NormalizeLid(_wantedLid);
+	if (!wanted) return _available.includes(DEFAULT_LID) ? DEFAULT_LID : _available[0];
+	if (_available.includes(wanted)) return wanted;
+	let caseInsensitive = _available.find((_lid) => _lid.toLowerCase() === wanted.toLowerCase());
+	if (caseInsensitive) return caseInsensitive;
+	if (Object.prototype.hasOwnProperty.call(LIDS_MAPS, wanted)) {
+		for (let candidate of LIDS_MAPS[wanted]) if (_available.includes(candidate)) return candidate;
+	}
+	let language = wanted.split('-')[0];
+	if (Object.prototype.hasOwnProperty.call(LIDS_MAIN_CULTURES, language)) {
+		let mainCulture = language + '-' + LIDS_MAIN_CULTURES[language];
+		if (_available.includes(mainCulture)) return mainCulture;
+	}
+	let byPrefix = _available.find((_lid) => _lid.split('-')[0].toLowerCase() === language);
+	if (byPrefix) return byPrefix;
+	return _available.includes(DEFAULT_LID) ? DEFAULT_LID : _available[0];
+}
+
+/** Directory holding the project dictionaries: env override or `<cwd>/i18x/gulp`. */
+function _DictionaryDir() {
+	return process.env.MICROGULP_I18X_DIR || join(process.cwd(), 'i18x', 'gulp');
+}
+
+/** Languages shipped by the project (en-US source is always available). */
+function _AvailableLids() {
+	if (availableLids) return availableLids;
+	let lids = [DEFAULT_LID];
+	try {
+		for (let entry of readdirSync(_DictionaryDir())) {
+			if (!entry.toLowerCase().endsWith('.json')) continue;
+			let lid = entry.slice(0, -5);
+			if (!lids.includes(lid)) lids.push(lid);
+		}
+	} catch {
+		// No dictionary directory — only the en-US source is available.
+	}
+	availableLids = lids;
+	return availableLids;
+}
+
+/** Resolves the active language from MICROGULP_LANG, OS locale, then default. */
+function _ResolveLid() {
+	let wanted = process.env.MICROGULP_LANG;
+	if (!wanted) {
+		try {
+			wanted = Intl.DateTimeFormat().resolvedOptions().locale;
+		} catch {
+			// Intl is always present in Node 22, but stay defensive.
+		}
+	}
+	return _BestAvailableLid(wanted || process.env.LANG || DEFAULT_LID, _AvailableLids());
+}
+
+/** @returns {string} the active localization id (cached after first use) */
+export function GetLid() {
+	if (!activeLid) activeLid = _ResolveLid();
+	return activeLid;
+}
+
+/**
+ * Overrides the active language explicitly and clears caches so the next
+ * translation reloads. Pass a falsy value to reset to automatic resolution.
+ * @param {string} [_lid]
+ */
+export function SetLid(_lid) {
+	activeLid = _lid ? _BestAvailableLid(_lid, _AvailableLids()) : null;
+}
+
+/** Loads and caches `<dir>/<lid>.json`; a missing/broken file yields source text. */
+function _LoadDictionary(_lid) {
+	if (dictionaryCache.has(_lid)) return dictionaryCache.get(_lid);
+	let dictionary = {};
+	try {
+		let filePath = join(_DictionaryDir(), _lid + '.json');
+		if (existsSync(filePath)) dictionary = JSON.parse(readFileSync(filePath, 'utf8'));
+	} catch {
+		// A malformed dictionary must not break the build — fall back to source.
+	}
+	dictionaryCache.set(_lid, dictionary);
+	return dictionary;
+}
+
+/** Substitutes `<name/>` placeholders; honors `format="…"` for int and clock times. */
+function _ApplyPlaceholders(_text, _values) {
+	let text = String(_text);
+	for (let key of Object.keys(_values ?? {})) {
+		let pattern = new RegExp('<' + key + '(?:\\s+format="([^"]*)")?\\s*/>', 'g');
+		text = text.replace(pattern, (_match, _formatName) => {
+			if (_formatName === 'int') return String(Math.round(Number(_values[key]) || 0));
+			if (_formatName === 'stdtime' || _formatName === 'stddatetime') {
+				let date = new Date(Number(_values[key]) || 0);
+				let lid = GetLid();
+				try {
+					return new Intl.DateTimeFormat(lid, {
+						...( _formatName === 'stddatetime'
+							? { year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }
+							: { hour: '2-digit', minute: '2-digit' }),
+						timeZone: GetTimeZone(),
+					}).format(date);
+				} catch {
+					return date.toISOString();
+				}
+			}
+			return String(_values[key]);
+		});
+	}
+	return text.replace(/<[^>]*>/g, '');
+}
+
+/**
+ * Translates a source phrase (including its context tag) into the active
+ * language and resolves placeholders. Unknown phrases fall back to the en-US
+ * source text with its tags stripped.
+ * @param {string} _text source phrase, e.g. 'Build ready<context="task log"/>'
+ * @param {object} [_values] placeholder values for `<name/>` tags
+ * @returns {string}
+ */
+export function Translate(_text, _values) {
+	if (_text == null) return '';
+	let source = String(_text);
+	let lid = GetLid();
+	let dictionary = lid === DEFAULT_LID ? null : _LoadDictionary(lid);
+	let translated = (dictionary && Object.prototype.hasOwnProperty.call(dictionary, source)) ? dictionary[source] : source;
+	return _ApplyPlaceholders(translated, _values);
+}
+
+/**
+ * console.log through i18x. Prefer the `<context="task log"/>` tag.
+ * @param {string} _text source phrase
+ * @param {object} [_values]
+ */
+export function Log(_text, _values) {
+	console.log(Translate(_text, _values));
+}
+
+/**
+ * console.warn through i18x. Prefer the `<context="task warning"/>` tag.
+ * @param {string} _text source phrase
+ * @param {object} [_values]
+ */
+export function Warn(_text, _values) {
+	console.warn(Translate(_text, _values));
+}
+
+/**
+ * console.error through i18x. Prefer the `<context="task error"/>` tag.
+ * Named LogError to avoid shadowing the global Error constructor.
+ * @param {string} _text source phrase
+ * @param {object} [_values]
+ */
+export function LogError(_text, _values) {
+	console.error(Translate(_text, _values));
+}
+
+/**
+ * µLib-compatible String-prototype API for gulpfiles that prefer the
+ * `"text<context=\"…\"/>".i18xTrans({ … })` ergonomics over the Log/Warn
+ * helpers. Installs `I18xTrans`/`i18xTrans` and `I18xRegister`/`i18xRegister`
+ * — but never overwrites an implementation already provided by µLib (µLib
+ * wins when both are loaded). Called automatically on import; also exported
+ * for explicit control.
+ */
+export function InstallStringExtensions() {
+	if (typeof String.prototype.I18xTrans !== 'function') {
+		Object.defineProperty(String.prototype, 'I18xTrans', {
+			value: function (_values) { return Translate(String(this), _values); },
+			writable: true, configurable: true,
+		});
+	}
+	if (typeof String.prototype.i18xTrans !== 'function') {
+		Object.defineProperty(String.prototype, 'i18xTrans', {
+			value: String.prototype.I18xTrans,
+			writable: true, configurable: true,
+		});
+	}
+	if (typeof String.prototype.I18xRegister !== 'function') {
+		Object.defineProperty(String.prototype, 'I18xRegister', {
+			value: function () { return String(this); },
+			writable: true, configurable: true,
+		});
+	}
+	if (typeof String.prototype.i18xRegister !== 'function') {
+		Object.defineProperty(String.prototype, 'i18xRegister', {
+			value: String.prototype.I18xRegister,
+			writable: true, configurable: true,
+		});
+	}
+}
+
+InstallStringExtensions();
+
+export default {
+	GetLid, SetLid, GetTimeZone, DateInTimeZone,
+	Translate, Log, Warn, LogError, InstallStringExtensions,
+};

package/src/index.mjs

@@ -28,6 +28,11 @@
  * @module gulp-mu-gulp-api
  */
 
+// Localized console output (i18x). Re-exported so tasks import everything
+// from one place: `import { Log, Warn, ReportProgress } from 'gulp-mu-gulp-api'`.
+export { Log, Warn, LogError, Translate, GetLid, SetLid, GetTimeZone, DateInTimeZone, InstallStringExtensions } from './i18x.mjs';
+import * as I18x from './i18x.mjs';
+
 let uiRequestCounter = 0;
 let ipcListenerAttached = false;
 let lastLoggedPercent = -1;
@@ -47,25 +52,20 @@ export const IsµGulp = IsMicroGulp;
 /** @deprecated Use {@link IsMicroGulp} or {@link IsµGulp}. */
 export const IsUGulp = IsMicroGulp;
 
-/**
- * Marks a µXXX task metadata string for i18x (American English source).
- * Appends the i18xe context tag for the property (`µDisplayName`,
- * `µDescription`, …) so the dashboard can translate it and a later
- * i18xe-server sync can pick it up. The classic gulp CLI ignores these
- * properties entirely.
+/*
+ * Task metadata (µDisplayName, µDescription, µTooltip, µGroup) is localized
+ * the same way as any other i18x phrase: with the context tag written *into*
+ * the source phrase and a String.prototype.i18xRegister() marker so the
+ * i18xe-sync tooling extracts it and the dashboard can translate it later.
+ *
+ *   MAKE_BUILDS.µDisplayName =
+ *       'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
  *
- * @param {string} _text source phrase
- * @param {'µDisplayName'|'µDescription'|'µTooltip'|'µGroup'} _contextProperty
- * @returns {string}
+ * i18xRegister() returns the phrase unchanged (the i18x key), so the classic
+ * gulp CLI keeps seeing a plain string while the dashboard translates it via
+ * the merged project dictionary. The prototype is installed by
+ * InstallStringExtensions() (auto-run on import of this module).
  */
-export function µMeta(_text, _contextProperty) {
-	let text = String(_text ?? '').trim();
-	if (!text || text.includes('<context="')) return text;
-	return text + '<context="' + _contextProperty + '"/>';
-}
-
-/** ASCII export alias for {@link µMeta}. */
-export const MicroGulpMeta = µMeta;
 
 // -------------------------------------------------
 // progress
@@ -111,6 +111,108 @@ export function CreateProgress(_label) {
 	};
 }
 
+// -------------------------------------------------
+// structured log output (table / tree)
+// -------------------------------------------------
+
+/**
+ * Sends a table to the dashboard log pane. The payload is JSON:
+ * `{ columns: string[] | {id, label}[], rows: (string|number)[][] | object[], hyphenate?: boolean }`.
+ * CLI fallback: a simple ASCII table on stdout.
+ *
+ * @param {object} _spec table descriptor
+ */
+export function LogTable(_spec) {
+	let payload = _NormalizeTableSpec(_spec);
+	if (IsMicroGulp()) {
+		process.send({ type: 'structured-log', format: 'table', payload });
+		return;
+	}
+	console.log(_AsciiTable(payload));
+}
+
+/**
+ * Sends a tree structure to the dashboard log pane. The payload is JSON:
+ * `{ label?: string, children?: object[], roots?: object[] }` where each node
+ * has `{ label, children? }`. CLI fallback: indented text lines.
+ *
+ * @param {object} _spec tree descriptor (single root or `{ roots: [...] }`)
+ */
+export function LogTree(_spec) {
+	let payload = _NormalizeTreeSpec(_spec);
+	if (IsMicroGulp()) {
+		process.send({ type: 'structured-log', format: 'tree', payload });
+		return;
+	}
+	for (let line of _AsciiTreeLines(payload)) console.log(line);
+}
+
+/**
+ * Sends an image gallery to the dashboard log pane. Each item needs a `src`
+ * (data URI or https URL) and a `label`; optional `caption` and per-item `title`.
+ * CLI fallback: lists labels and src lengths on stdout.
+ *
+ * @param {object} _spec `{ title?, columns?, items: { label, src, caption?, title? }[] }`
+ */
+export function LogGallery(_spec) {
+	let payload = _NormalizeGallerySpec(_spec);
+	if (IsMicroGulp()) {
+		process.send({ type: 'structured-log', format: 'gallery', payload });
+		return;
+	}
+	console.log(_AsciiGallery(payload));
+}
+
+/**
+ * Renders µCSS BuildSkin `report.debug.previews` as a thumbnail gallery.
+ * Items without `thumbDataUri` are omitted (paths-only assets stay in the text log).
+ *
+ * @param {object[]} _previews preview entries from `report.debug.previews`
+ * @param {object} [_options] `{ title?, columns? }`
+ */
+export function LogAssetPreviews(_previews, _options = {}) {
+	let items = (_previews ?? [])
+		.filter((_entry) => _entry?.thumbDataUri)
+		.map((_entry) => ({
+			label: String(_entry.relPath ?? _entry.path ?? ''),
+			src: _entry.thumbDataUri,
+			caption: [
+				_entry.step,
+				_entry.skipped ? 'cached' : null,
+				_entry.width && _entry.height ? `${_entry.width}\u00d7${_entry.height}` : null,
+			].filter(Boolean).join(' \u00b7 '),
+		}));
+	if (!items.length) return;
+	LogGallery({
+		title: _options.title,
+		columns: _options.columns ?? 4,
+		items,
+	});
+}
+
+/**
+ * Convenience wrapper for a full µCSS `BuildSkin` debug block: summary table
+ * plus thumbnail gallery when `report.debug` is present.
+ *
+ * @param {object} _report BuildSkin return value
+ * @param {object} [_options] `{ title?, columns?, table?: boolean }`
+ */
+export function LogBuildDebugReport(_report, _options = {}) {
+	let debug = _report?.debug;
+	if (!debug) return;
+	if (_options.table !== false && debug.summary) {
+		LogTable({
+			columns: [{ id: 'metric', label: 'Metric' }, { id: 'value', label: 'Value' }],
+			rows: Object.entries(debug.summary).map(([metric, value]) => ({ metric, value: String(value) })),
+			hyphenate: false,
+		});
+	}
+	LogAssetPreviews(debug.previews, {
+		title: _options.title ?? 'Generated assets',
+		columns: _options.columns,
+	});
+}
+
 // -------------------------------------------------
 // sound & speech
 // -------------------------------------------------
@@ -333,12 +435,92 @@ async function _FallbackField(_field) {
 	}
 }
 
+function _NormalizeColumn(_column, _index) {
+	if (typeof _column === 'string') return { id: 'c' + _index, label: _column };
+	return { id: String(_column.id ?? 'c' + _index), label: String(_column.label ?? _column.id ?? 'c' + _index) };
+}
+
+function _NormalizeTableSpec(_spec) {
+	let columns = (_spec?.columns ?? []).map(_NormalizeColumn);
+	let rows = _spec?.rows ?? [];
+	let normalizedRows = rows.map((_row) => {
+		if (Array.isArray(_row)) {
+			let obj = {};
+			for (let c = 0; c < columns.length; c++) obj[columns[c].id] = _row[c] ?? '';
+			return obj;
+		}
+		return _row;
+	});
+	return { columns, rows: normalizedRows, hyphenate: _spec?.hyphenate !== false };
+}
+
+function _NormalizeTreeSpec(_spec) {
+	if (_spec?.roots) return { roots: _spec.roots };
+	if (_spec?.label != null || _spec?.children) return { roots: [_spec] };
+	return { roots: [] };
+}
+
+function _AsciiTable(_payload) {
+	let headers = _payload.columns.map((_c) => _c.label);
+	let widths = headers.map((_h) => _h.length);
+	for (let row of _payload.rows) {
+		for (let c = 0; c < _payload.columns.length; c++) {
+			let cell = String(row[_payload.columns[c].id] ?? '');
+			widths[c] = Math.max(widths[c], cell.length);
+		}
+	}
+	let sep = widths.map((_w) => '-'.repeat(_w)).join('-+-');
+	let lines = [headers.map((_h, _i) => _h.padEnd(widths[_i])).join(' | ')];
+	lines.push(sep);
+	for (let row of _payload.rows) {
+		lines.push(_payload.columns.map((_col, _i) => String(row[_col.id] ?? '').padEnd(widths[_i])).join(' | '));
+	}
+	return lines.join('\n');
+}
+
+function _AsciiTreeLines(_payload, _indent = '', _roots = null) {
+	let roots = _roots ?? _payload.roots ?? [];
+	let lines = [];
+	for (let i = 0; i < roots.length; i++) {
+		let node = roots[i];
+		let branch = i < roots.length - 1 ? '├─ ' : '└─ ';
+		lines.push(_indent + branch + String(node.label ?? ''));
+		let childIndent = _indent + (i < roots.length - 1 ? '│  ' : '   ');
+		if (node.children?.length) lines.push(..._AsciiTreeLines(_payload, childIndent, node.children));
+	}
+	return lines;
+}
+
+function _NormalizeGallerySpec(_spec) {
+	let columns = Math.max(1, Math.min(8, Number(_spec?.columns) || 4));
+	let items = (_spec?.items ?? []).map((_item) => ({
+		label: String(_item?.label ?? ''),
+		src: String(_item?.src ?? ''),
+		caption: _item?.caption != null ? String(_item.caption) : '',
+		title: _item?.title != null ? String(_item.title) : '',
+	})).filter((_item) => _item.src);
+	return {
+		title: _spec?.title != null ? String(_spec.title) : '',
+		columns,
+		items,
+	};
+}
+
+function _AsciiGallery(_payload) {
+	let lines = [];
+	if (_payload.title) lines.push(_payload.title);
+	for (let item of _payload.items) {
+		let meta = item.caption ? ` (${item.caption})` : '';
+		let srcHint = item.src.startsWith('data:') ? `[data URI, ${item.src.length} chars]` : item.src;
+		lines.push(`  ${item.label}${meta}: ${srcHint}`);
+	}
+	return lines.join('\n');
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
 	IsUGulp,
-	µMeta,
-	MicroGulpMeta,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,
@@ -349,4 +531,18 @@ export default {
 	RequestFontInput,
 	RequestSelectInput,
 	RequestMultiSelectInput,
+	Log: I18x.Log,
+	Warn: I18x.Warn,
+	LogError: I18x.LogError,
+	Translate: I18x.Translate,
+	GetLid: I18x.GetLid,
+	SetLid: I18x.SetLid,
+	GetTimeZone: I18x.GetTimeZone,
+	DateInTimeZone: I18x.DateInTimeZone,
+	InstallStringExtensions: I18x.InstallStringExtensions,
+	LogTable,
+	LogTree,
+	LogGallery,
+	LogAssetPreviews,
+	LogBuildDebugReport,
 };